> ## 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 uses its application API key (`Authorization: Basic <API_KEY>`) to mint 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 **API Key**, **User ID**, and **Account ID**.
2. From your backend, call `generateUserAccessToken` on `https://transactional-graph.fluzapp.com/api/v1/graphql` (staging: `https://transactional-graph.staging.fluzapp.com/api/v1/graphql`) with the header `Authorization: Basic <API_KEY>`, passing your `userId`, `accountId`, and the scopes you need as arguments.
3. Attach the returned `token` 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 at the OAuth token exchange endpoint — see [the OAuth grant flow](/client-facing-o-auth-grant-flow).
5. Refresh customer-scoped tokens via the [OAuth token refresh endpoint](/refresh-o-auth-access-token) 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`                                                               |
| Deposits        | `MAKE_DEPOSIT`                                                                                                               |
| Funding sources | `LIST_PAYMENT`, `MANAGE_PAYMENT`                                                                                             |
| Card data (PCI) | `PCI_COMPLIANCE` — granted at the application level to PCI-compliant developers; cannot be requested when generating a token |

Request the minimum you need. Mint a new token when you need broader access.

## Token lifetime

* **Access tokens:** short-lived JWTs (minutes, not hours). Mint a new one when it expires — see [Replace an expired access token](/get-started/refresh-expired-access-token).
* **OAuth customer tokens:** refreshable via the [OAuth token refresh endpoint](/refresh-o-auth-access-token).
* **Application API key:** valid until rotated in the dashboard.

<Warning>
  Never ship your API key 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>