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

# Authenticate requests to the Aria Compute API

> Session JWTs, bfvk API keys, and query-token downloads: how to obtain each credential and which endpoints accept it.

The Aria Compute API supports three ways to authenticate a request. Which one you use depends on the endpoint: user-scoped endpoints take a session JWT, gateway and model downloads take an API key, and browser-initiated download links can use a short-lived query token.

## The three credentials

| Credential  | Header or param                  | Obtained from                            | Used for                                                              |
| ----------- | -------------------------------- | ---------------------------------------- | --------------------------------------------------------------------- |
| Session JWT | `Authorization: Bearer <jwt>`    | `POST /api/auth/login` or OAuth callback | All `/api/auth/*`, `/api/billing/*`, `/api/api-keys` endpoints        |
| API key     | `Authorization: Bearer bfvk-...` | `POST /api/api-keys`                     | Model downloads, per-site gateway (`gateway.ariacompute.com` / `.cn`) |
| Query token | `?token=<jwt>`                   | Same JWT, but in the URL                 | Browser-initiated file downloads (invoices, receipts, models)         |

## Get a session JWT

Sign in with email, phone, or OAuth. The response includes a JWT.

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

```json theme={null}
{
  "token": "eyJhbGciOi...",
  "user": { "id": "usr_123", "email": "you@example.com" }
}
```

Send that token as `Authorization: Bearer eyJhbGciOi...` on every user-scoped request. If the account has 2FA enabled, the login response indicates a challenge and you must call `POST /api/auth/2fa/verify` before receiving a full session.

## Create an API key

API keys are Bifrost virtual keys prefixed with `bfvk-`. They are created from the dashboard or via the API and used against the per-site gateway and authenticated download endpoints.

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

The full key is returned once in the response as `key`. Store it in a secret manager. Later `GET /api/api-keys` responses only return `prefix`, never the full value.

<Warning>
  Never embed a `bfvk-` key in client-side code. Use it from a server or CLI only.
</Warning>

## Query-token downloads

Some file endpoints support `?token=<jwt>` so that a plain `<a href>` in the browser can download the file without setting headers. This applies to:

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

The token is the same session JWT you use in the `Authorization` header.

## Failure modes

| Status                  | Cause                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------ |
| `401 Unauthorized`      | Missing, expired, or invalid session token or API key.                               |
| `403 Forbidden`         | Authenticated but not authorized (for example, non-admin calling an admin endpoint). |
| `429 Too Many Requests` | Rate limit tripped. Back off and retry.                                              |

Session tokens are short-lived. Re-authenticate by calling `POST /api/auth/login` when the current token expires.


## Related topics

- [Python client for the Aria Compute API](/sdks/python.md)
- [Go client for the Aria Compute API](/sdks/go.md)
- [Node.js client for the Aria Compute API](/sdks/nodejs.md)
- [Aria Compute REST API reference](/api-reference/introduction.md)
- [Use the Aria Compute API from cURL](/sdks/curl.md)