> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 身份验证参考

> 使用你的 API key 铸造用户访问令牌的精确请求/响应格式。

概念性概览请参见 [身份验证](/concepts/authentication)。本页记录了在事务图上铸造令牌的精确 GraphQL 合同：

| 环境         | 端点                                                               |
| ---------- | ---------------------------------------------------------------- |
| Staging    | `https://transactional-graph.staging.fluzapp.com/api/v1/graphql` |
| Production | `https://transactional-graph.fluzapp.com/api/v1/graphql`         |

## `generateUserAccessToken`

使用你的应用程序 **API key** 铸造用户访问令牌。API key 通过 `Authorization: Basic <API_KEY>` 请求头发送——它绝不会作为 GraphQL 参数传递。该令牌针对一个 `userId` / `accountId` 对（与 API key 一同在开发者控制台中显示）进行铸造，并携带你请求的 scopes。

### 请求

```http theme={null}
POST /api/v1/graphql HTTP/1.1
Host: transactional-graph.staging.fluzapp.com
Authorization: Basic <API_KEY>
Content-Type: application/json

{
  "query": "mutation ($userId: UUID!, $accountId: UUID!, $scopes: [ScopeType!]!) { generateUserAccessToken(userId: $userId, accountId: $accountId, scopes: $scopes) { token scopes } }",
  "variables": {
    "userId": "<USER_ID>",
    "accountId": "<ACCOUNT_ID>",
    "scopes": ["LIST_OFFERS", "PURCHASE_GIFTCARD"]
  }
}
```

可选参数 `seatId: UUID` 用于选择用于交易的席位；默认为最近创建的席位。完整的参数参考见 [generateUserAccessToken](/api-reference/mutations/generate-user-access-token)。

### 响应

```json theme={null}
{
  "data": {
    "generateUserAccessToken": {
      "token": "eyJhbGciOi...",
      "scopes": ["LIST_OFFERS", "PURCHASE_GIFTCARD"]
    }
  }
}
```

在后续请求中，将返回的 `token` 作为 `Authorization: Bearer <token>` 附加。令牌是短期有效的 JWT——当其过期时需铸造新的令牌（参见 [替换已过期的访问令牌](/get-started/refresh-expired-access-token)）。

### 要求

* 用户必须已授予你的应用程序所请求的 scopes；未知或未授予的 scopes 将导致该 mutation 失败。
* 生成令牌时不能请求 `PCI_COMPLIANCE`——它在应用程序级别授予符合 PCI 的开发者。

## 发现 `userId` / `accountId`

同样通过 `Basic <API_KEY>` 授权：

* [`getApplicationUsers`](/api-reference/queries/get-application-users) —— 已向你的应用授予 scopes 的用户及其账户。
* [`getAccountsByUserId`](/api-reference/queries/get-accounts-by-user-id) —— 给定用户的所有账户。
* [`getApplicationScopes`](/api-reference/queries/get-application-scopes) —— 你的应用可用的 scopes。

## 客户账户（OAuth 平台）

如果你正在构建在客户账户上运行的平台，客户需先通过 OAuth 授权流程授权你的应用，你的服务器随后在令牌交换端点交换所得的 code——参见 [OAuth 授权流程](/client-facing-o-auth-grant-flow) 和 [构建平台](/build-a-platform)。

## Scopes

参见 [身份验证](/concepts/authentication#scopes) 中的 scope 表。未知的 scopes 会导致该 mutation 失败。