> ## 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 凭证和访问令牌

> 将你的 API key 交换为短期有效、具备范围的用户访问令牌。

## 获取你的 API 凭证

在 Developer Console 中创建应用后，选择该应用即可找到其 **API Key**、**User ID** 和 **Account ID**。

<Info>
  **在哪里找到：** [Developers 页面](https://uni.staging.fluzapp.com/developers)，在你创建的应用内部。这些凭证用于 API key 授权 —— 主要用于管理类调用以及生成用户访问令牌。
</Info>

![获取 API 凭证](https://files.readme.io/d1b78cd2ecfef1f945a9685f81efe0a8b30b7324d32d5ee62e610bced35585b4-obtain_api_creds.gif)

每个 Fluz API 请求都会在 `Authorization` 头中使用一个**用户访问令牌**。你可以通过调用 OAuth 服务的 `generateUserAccessToken` mutation，使用应用的 `clientId` 和 `clientSecret` 来铸造该令牌。

## 生成访问令牌

```bash theme={null}
curl -X POST https://oauth-service.fluzapp.com/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ($clientId: String!, $clientSecret: String!, $scopes: [Scope!]!) { generateUserAccessToken(clientId: $clientId, clientSecret: $clientSecret, scopes: $scopes) { accessToken expiresIn scopes } }",
    "variables": {
      "clientId": "<APPLICATION_CLIENT_ID>",
      "clientSecret": "<APPLICATION_CLIENT_SECRET>",
      "scopes": ["LIST_OFFERS", "PURCHASE_GIFTCARD", "REVEAL_GIFTCARD"]
    }
  }'
```

响应包含访问令牌、其有效期以及所携带的 scopes：

```json theme={null}
{
  "data": {
    "generateUserAccessToken": {
      "accessToken": "eyJhbGciOi...",
      "expiresIn": 3600,
      "scopes": ["LIST_OFFERS", "PURCHASE_GIFTCARD", "REVEAL_GIFTCARD"]
    }
  }
}
```

## 使用令牌

将令牌附加到针对 transactional graph 的每个 GraphQL 请求中：

```bash theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ viewer { id email } }"}'
```

<Warning>
  切勿将 `clientSecret` 值下发到浏览器或移动端客户端。请在服务端铸造访问令牌，并在必要时仅将令牌转发给客户端。
</Warning>

## 在过期前刷新

访问令牌为短期有效。在当前令牌过期之前请求一个新的 —— 不要等到收到 `401`。有关确切调用，请参阅 [刷新已过期的访问令牌](/get-started/refresh-expired-access-token)，有关完整流程（包括面向客户范围的 OAuth 授权），请参阅 [认证](/concepts/authentication)。

## 后续步骤

<CardGroup cols={2}>
  <Card title="快速入门：你的首次礼品卡购买" icon="gift" href="/quickstart">
    端到端跑通完整 happy path —— 存入资金、购买礼品卡，并在沙盒中展示它。
  </Card>

  <Card title="刷新已过期令牌" icon="rotate-cw" href="/get-started/refresh-expired-access-token">
    使用刷新令牌交换新的访问令牌，无需重新执行凭证流程。
  </Card>
</CardGroup>

<StickyContactSalesBanner />