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

# Authentication

> API keys for your application, sign-in tokens for managing keys.

Every request except `/healthz` needs an `Authorization` header:

```text theme={null}
Authorization: Bearer <credential>
```

There are two kinds of credential.

| Credential | Looks like | Used for |
| - | - | - |
| API key | `tazo_sk_<key id>.<secret>` | `GET /v1/models` and `POST /v1/decisions` |
| Access token | A signed-in user's OIDC (Cognito) access token | Everything an API key can do, plus managing API keys |

Applications should use API keys. Access tokens are short-lived and meant for
the signed-in playground.

> [!NOTE]
>
> API keys cannot create, list, or revoke keys. Calling `/v1/api-keys` with an
> API key returns `403` with the code `api_key_management_requires_login`.

## Managing keys

Keys are managed with `POST`, `GET`, and `DELETE` on `/v1/api-keys`, using a
sign-in access token. You can also do this from the playground.

> **[Create](/api-reference/api-keys/create-an-api-key.md)**

> **[List](/api-reference/api-keys/list-api-keys.md)**

> **[Revoke](/api-reference/api-keys/revoke-an-api-key.md)**

* **Naming:** names are trimmed and must be 1 to 40 characters.
* **Expiry:** `7d`, `30d` (default), or `never`.
* **No account limit:** there is no cap on how many keys you can create.
* **Ownership:** a key belongs to the account that created it. Requests made
  with a key and with that account's login share the same identity, including
  [idempotency](/guides/idempotency.md) scope.
* **Revocation:** takes effect for requests authenticated after it completes.
  Decisions already accepted keep processing.
* **History:** expired and revoked keys stay in your list for about 30 days,
  then disappear. Revoking a key that is gone returns `404`.

Each key has metadata: `id`, `name`, `last4`, `createdAt`, `expiresAt`,
`revokedAt`, and `lastUsedAt`. Dates are UTC ISO 8601 strings, or `null`.
`lastUsedAt` is best effort and updates at most once a minute.

## Keep keys safe

* Store keys in a secret manager or environment variable, never in browser code.
* Do not log `Authorization` headers or key creation responses.
* If you lose a secret, revoke that key and create a new one. A secret cannot be
  recovered.
* A timed-out `POST /v1/api-keys` may still have created a key. Reload the list
  and revoke any key you did not receive a secret for.

## Authentication errors

| Status | Code | Meaning |
| - | - | - |
| 401 | `missing_access_token` | No bearer credential was sent. |
| 401 | `invalid_access_token` | The access token is invalid or expired. |
| 401 | `invalid_api_key` | The API key is invalid, expired, or revoked. |
| 403 | `api_key_management_requires_login` | An API key was used on `/v1/api-keys`. |
| 503 | `authentication_not_configured` | Sign-in is not configured on the server. |
| 503 | `api_keys_not_configured` | API keys are not configured on the server. |
| 503 | `api_key_service_unavailable` | Key storage is temporarily unavailable. Requests fail closed. |

See [Errors](/guides/errors.md) for the full error format.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.