> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API authentication: session tokens and API keys

> Detailed reference for the three ways to authenticate to the Aria Compute API: session JWTs, bfvk API keys, and query-token file downloads.

The Aria Compute API accepts three credential types. This page explains where each one comes from, how to send it, and which endpoints require which.

## Credential summary

| Credential  | Sent as                               | Obtained from                                                       | Typical use                      |
| ----------- | ------------------------------------- | ------------------------------------------------------------------- | -------------------------------- |
| Session JWT | `Authorization: Bearer eyJhbGciOi...` | `POST /api/auth/login`, OAuth callback, `POST /api/auth/2fa/verify` | Dashboard-scoped calls           |
| API key     | `Authorization: Bearer bfvk-...`      | `POST /api/api-keys`                                                | Gateway and model downloads      |
| Query token | `?token=eyJhbGciOi...`                | Same JWT as above                                                   | Browser-initiated file downloads |

## Session JWT

```bash theme={null}
curl -X POST https://ariacompute.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"identifier": "you@example.com", "password": "..."}'
```

Send the returned `token` as `Authorization: Bearer` on every user-scoped request. Session JWTs are short-lived; call login again to refresh.

If 2FA is enabled, the login response indicates a challenge and you must call `POST /api/auth/2fa/verify` to receive the final session.

## API key (bfvk-)

Create keys with a session JWT:

```bash theme={null}
curl -X POST https://ariacompute.com/api/api-keys \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -d '{"name": "production"}'
```

The response includes the full key exactly once as `key`. Store it in a secret manager and send it as `Authorization: Bearer bfvk-...` on model downloads and gateway calls.

<Warning>
  Never expose a `bfvk-` key in client-side JavaScript, mobile apps, or public repositories. Anyone who reads the key can spend your wallet.
</Warning>

## Query token

Some file endpoints accept `?token=<jwt>` so an anchor tag in the browser can trigger the download without setting headers. The token is the same session JWT.

Supported endpoints:

* `GET /api/models/{slug}/download?token=...`
* `GET /api/billing/invoices/{paymentId}/download?token=...`
* `GET /api/billing/receipts/{paymentId}/download?token=...`

## Token expiration and refresh

Session JWTs expire on their own; call `POST /api/auth/login` (or the 2FA verify endpoint) again for a fresh token. API keys stay valid until you `DELETE` them.

## Failure modes

| Status | Cause                                    |
| ------ | ---------------------------------------- |
| `401`  | Missing, expired, or invalid credential. |
| `403`  | Authenticated but not authorized.        |
| `429`  | Too many requests. Back off and retry.   |


## Related topics

- [Aria Compute Documentation](/index.md)
- [Aria Compute REST API reference](/api-reference/introduction.md)
- [POST /api/auth/logout — revoke the current session](/api-reference/auth/logout.md)
- [Download Aria model bundles from the registry](/guides/download-models.md)
- [GET /api/api-keys — list your API keys](/api-reference/api-keys/list.md)