> ## 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 金鑰、使用者存取權杖與範圍的運作方式——包含你的自有帳戶與已連結的客戶帳戶。

每個 Fluz API 請求都會在 `Authorization` 標頭中攜帶一個**使用者存取權杖**。如何取得該權杖，取決於你正在操作的是哪個帳戶。

## 兩條路徑，同一個 API

<Columns cols={2}>
  <Card title="你的自有帳戶" icon="user">
    `API key` → `Your token`

    你的伺服器以應用程式 API 金鑰交換一個以你的 Fluz 帳戶為範圍的權杖。
  </Card>

  <Card title="客戶的帳戶" icon="users">
    `OAuth grant` → `Their token`

    客戶授權你的應用程式，Fluz 會回傳一個以其帳戶為範圍的權杖。
  </Card>
</Columns>

一旦你持有權杖，其餘的 API 皆相同。在你的權杖上呼叫 `createVirtualCard` 會在你的錢包建立一張卡；在客戶權杖上呼叫 `createVirtualCard` 會在他們的錢包建立。

## 路徑 1 — 你的自有帳戶

1. 在控制台中建立一個應用程式，並複製其 `clientId` 與 `clientSecret`。
2. 從你的後端，使用 `clientId`、`clientSecret` 與所需範圍，對 `https://oauth-service.fluzapp.com/graphql` 呼叫 `generateUserAccessToken`。
3. 將回傳的 `accessToken` 以 `Authorization: Bearer <token>` 附加在對 transactional graph 的每個請求上。

參見 [API 憑證](/get-started/api-credentials) 以取得完整範例。

## 路徑 2 — 客戶的帳戶

當你在打造一個平台時使用此法——例如代你的使用者發卡。

1. 將客戶重新導向至 Fluz 的 OAuth 授權 URL，並附上你的 `clientId`、請求的範圍與 `redirect_uri`。
2. 客戶登入並授予你的範圍。
3. Fluz 會帶著短效的授權 `code` 導回。
4. 你的伺服器以該 code 與你的應用程式憑證呼叫 `generateUserAccessToken`，交換為以客戶為範圍的存取權杖。
5. 在到期前刷新以客戶為範圍的權杖，無需再次提示客戶。

完整教學見 [建立平台](/build-a-platform)。

## 範圍（Scopes）

權杖攜帶一組明確的範圍。依能力常見如下：

| 區域    | 範圍                                                                                                          |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| 禮品卡   | `LIST_OFFERS`, `PURCHASE_GIFTCARD`, `REVEAL_GIFTCARD`, `LIST_PURCHASES`                                     |
| 虛擬卡   | `CREATE_VIRTUALCARD`, `REVEAL_VIRTUALCARD`, `EDIT_VIRTUALCARD`, `PCI_COMPLIANCE`, `CREATE_SHARE_LINK`       |
| 錢包與轉帳 | `MAKE_DEPOSIT`, `MAKE_WITHDRAWAL`, `MAKE_INTERNAL_TRANSFER`, `MAKE_PAYOUT_TRANSFER_SEND`, `QUERY_RECIPIENT` |
| 資金來源  | `LIST_PAYMENT`, `MANAGE_PAYMENT`                                                                            |
| 授權使用者 | `MANAGE_SUBUSERS`, `VIEW_SUBUSERS`                                                                          |
| 核准    | `LIST_APPROVALS`, `MANAGE_APPROVALS`                                                                        |
| 驗證    | `VERIFY_KYC`, `REGISTER_BUSINESS`                                                                           |

只請求你所需的最小範圍。每個範圍也有一個 `REQUEST_*` 變體，與核准流程搭配使用——請見 [核准與請求](/features/approvals-and-requests)。當你需要更廣的存取時，鑄造一個新權杖。

## 權杖有效期

* \*\*Access tokens：\*\*短效。在 `expiresIn` 到期前刷新。
* \*\*OAuth 客戶權杖：\*\*可透過 OAuth 服務刷新。
* \*\*應用程式 `clientSecret`：\*\*在控制台輪替前都有效。

<Warning>
  切勿將 `clientSecret` 送到瀏覽器或行動客戶端。它能為你的帳戶鑄造權杖；一旦外洩，等同於洩漏你的憑證。
</Warning>

## 下一步

<CardGroup cols={2}>
  <Card title="取得你的 API 憑證" icon="key" href="/get-started/api-credentials">
    實作路徑 1——為你的自有帳戶鑄造權杖並發出呼叫。
  </Card>

  <Card title="建立平台" icon="users" href="/build-a-platform">
    實作路徑 2——透過 OAuth 授權流程連結客戶帳戶。
  </Card>
</CardGroup>