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

> The exact request/response shapes for minting user access tokens with your API key.

For the conceptual overview, see [Authentication](/concepts/authentication). This page documents the exact GraphQL contract for minting tokens on the transactional graph:

| Environment | Endpoint                                                         |
| ----------- | ---------------------------------------------------------------- |
| Staging     | `https://transactional-graph.staging.fluzapp.com/api/v1/graphql` |
| Production  | `https://transactional-graph.fluzapp.com/api/v1/graphql`         |

## `generateUserAccessToken`

Mint a user access token with your application's **API key**. The API key is sent in the `Authorization: Basic <API_KEY>` header — it is never passed as a GraphQL argument. The token is minted for a `userId` / `accountId` pair (shown alongside your API key in the Developer Console) and carries the scopes you request.

### Request

```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"]
  }
}
```

An optional `seatId: UUID` argument selects the seat used for transactions; it defaults to the most recently created seat. See the full argument reference at [generateUserAccessToken](/api-reference/mutations/generate-user-access-token).

### Response

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

Attach the returned `token` as `Authorization: Bearer <token>` on subsequent requests. Tokens are short-lived JWTs — mint a new one when it expires (see [Replace an expired access token](/get-started/refresh-expired-access-token)).

### Requirements

* The user must have granted your application the requested scopes; unknown or ungranted scopes cause the mutation to fail.
* `PCI_COMPLIANCE` cannot be requested when generating a token — it is granted at the application level to PCI-compliant developers.

## Discovering `userId` / `accountId`

Also authorized by `Basic <API_KEY>`:

* [`getApplicationUsers`](/api-reference/queries/get-application-users) — the users who have granted scopes to your application, with their accounts.
* [`getAccountsByUserId`](/api-reference/queries/get-accounts-by-user-id) — all accounts for a given user.
* [`getApplicationScopes`](/api-reference/queries/get-application-scopes) — the scopes available to your application.

## Customer accounts (OAuth platforms)

If you are building a platform that operates on customer accounts, the customer first authorizes your app through the OAuth grant flow, and your server exchanges the resulting code at the token exchange endpoint — see [the OAuth grant flow](/client-facing-o-auth-grant-flow) and [Build a platform](/build-a-platform).

## Scopes

See the scope table in [Authentication](/concepts/authentication#scopes). Unknown scopes cause the mutation to fail.