> ## 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.

# Authentication

> How API keys, user access tokens, and scopes work — for your own account and for connected customer accounts.

Every Fluz API request carries a **user access token** in the `Authorization` header. How you get that token depends on whose account you're operating on.

## Two paths, one API

<Columns cols={2}>
  <Card title="Your own account" icon="user">
    `API key` → `Your token`

    Your server exchanges its application API key for a token scoped to your Fluz account.
  </Card>

  <Card title="A customer's account" icon="users">
    `OAuth grant` → `Their token`

    A customer authorizes your app, and Fluz returns a token scoped to their account.
  </Card>
</Columns>

Once you hold a token, the rest of the API is identical. `createVirtualCard` on your token creates a card on your wallet; `createVirtualCard` on a customer token creates it on theirs.

## Path 1 — your own account

1. In the dashboard, create an application and copy its `clientId` and `clientSecret`.
2. From your backend, call `generateUserAccessToken` on `https://oauth-service.fluzapp.com/graphql` with your `clientId`, `clientSecret`, and the scopes you need.
3. Attach the returned `accessToken` as `Authorization: Bearer <token>` on every request to the transactional graph.

See [API credentials](/get-started/api-credentials) for a full example.

## Path 2 — a customer's account

Use this when you're building a platform — e.g. issuing cards on behalf of your users.

1. Redirect the customer to Fluz's OAuth authorize URL with your `clientId`, requested scopes, and `redirect_uri`.
2. The customer signs in and grants your scopes.
3. Fluz redirects back with a short-lived authorization `code`.
4. Your server exchanges the code for a customer-scoped access token by calling `generateUserAccessToken` with the code and your application credentials.
5. Refresh customer-scoped tokens before they expire without re-prompting the customer.

Full walkthrough in [Build a platform](/build-a-platform).

## Scopes

Tokens carry an explicit set of scopes. Common ones by capability:

| Area                | Scopes                                                                                                      |
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
| Gift cards          | `LIST_OFFERS`, `PURCHASE_GIFTCARD`, `REVEAL_GIFTCARD`, `LIST_PURCHASES`                                     |
| Virtual cards       | `CREATE_VIRTUALCARD`, `REVEAL_VIRTUALCARD`, `EDIT_VIRTUALCARD`, `PCI_COMPLIANCE`, `CREATE_SHARE_LINK`       |
| Wallets & transfers | `MAKE_DEPOSIT`, `MAKE_WITHDRAWAL`, `MAKE_INTERNAL_TRANSFER`, `MAKE_PAYOUT_TRANSFER_SEND`, `QUERY_RECIPIENT` |
| Funding sources     | `LIST_PAYMENT`, `MANAGE_PAYMENT`                                                                            |
| Authorized users    | `MANAGE_SUBUSERS`, `VIEW_SUBUSERS`                                                                          |
| Approvals           | `LIST_APPROVALS`, `MANAGE_APPROVALS`                                                                        |
| Verification        | `VERIFY_KYC`, `REGISTER_BUSINESS`                                                                           |

Request the minimum you need. Every scope also has a `REQUEST_*` variant used with the approvals flow — see [Approvals & Requests](/features/approvals-and-requests). Mint a new token when you need broader access.

## Token lifetime

* **Access tokens:** short-lived. Refresh before `expiresIn` elapses.
* **OAuth customer tokens:** refreshable via the OAuth service.
* **Application `clientSecret`:** valid until rotated in the dashboard.

<Warning>
  Never ship a `clientSecret` to a browser or mobile client. It mints tokens for your account; leaking one is equivalent to leaking your credentials.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Get your API credentials" icon="key" href="/get-started/api-credentials">
    Path 1 in practice — mint a token for your own account and make a call.
  </Card>

  <Card title="Build a platform" icon="users" href="/build-a-platform">
    Path 2 in practice — connect customer accounts with the OAuth grant flow.
  </Card>
</CardGroup>