# Authentication

Send your API key in a request header with the Bearer scheme.

Every request carries an API key in the `Authorization` header. The examples only reference the `CHENVOYA_API_KEY` environment variable and never show a key.

## Send the API key

Write `Bearer`, a space and the API key in the `Authorization` header:

```bash
Authorization: Bearer ${CHENVOYA_API_KEY}
```

A missing or invalid key returns `401 authentication_failed`, and the `WWW-Authenticate` response header names the Bearer scheme.

## Create and keep keys

- Create API keys on the [API keys](./integration.html) page of the console; one API key works with every model.
- Keep and use API keys on servers only, in environment variables or a secret manager. Never put one in a web page, an app, a code repository, a document or a log.
- If you suspect a leak, suspend the key in the console, create a new one and replace the value on your servers.

## Permissions and teams

API keys belong to a team, and tasks and assets are separated by team: a task created with any API key of your team can be read with any other key of the same team. Tasks and assets of other teams always return `task_not_found` or `asset_not_found`.

Registering and reading assets needs an API key with `service.use` permission; otherwise the answer is `403 permission_denied`.

## Authentication errors

| Status | error.code | What to do |
| --- | --- | --- |
| 401 | `authentication_failed` | Check the API key after `Authorization: Bearer`. |
| 403 | `permission_denied` | Use an API key that has `service.use` permission. |
| 409 | `key_provisioning_incomplete` | The key's spend limit setup did not finish: delete the key and create a new one. |

## Next steps

- [Request conventions](./api-docs-en-conventions.md): Shared rules for the API address, JSON, request IDs, times, amounts and paging.
- [Quickstart](./api-docs-en-quickstart.md): Generate your first video in three steps: create an API key, submit a task, get the result.
- [Error codes](./api-docs-en-api-errors.md): Every error.code with its meaning, status and endpoints.