# Authentication and API keys

All Gateway API requests require authentication with an Ethen API key sent as a
Bearer token.

## Sending the API key

Include the key in the `Authorization` header:

```http
Authorization: Bearer ***
```

If the header is missing, the Gateway returns a `401` error with code
`missing_api_key`. If the key is invalid, revoked, or expired, it returns `401`
with code `invalid_api_key`, `revoked_api_key`, or `expired_api_key`.

## Key scopes

Each API key is assigned one or more scopes that control what operations it can
perform:

| Scope | Description |
|---|---|
| `gateway:invoke` | Create chat completions and manage streams. |
| `gateway:read` | View request logs, usage summaries, and stream state. |

A key without the `gateway:invoke` scope receives a `403` error with code
`insufficient_scope` when making chat completion requests.

## Creating a key

Keys are created in the **API Keys** dashboard within the Gateway product. The
raw key is displayed only once at creation time. The Gateway stores only a
one-way hash of the key, along with its prefix and suffix for identification.

## Key lifecycle

- **Active** — the key works for all scoped operations.
- **Expired** — keys can be assigned an expiration date. Expired keys return
  `expired_api_key`.
- **Revoked** — keys can be revoked at any time. Revoked keys return
  `revoked_api_key`.

## Environment and project isolation

Every key is bound to a single project and environment (`live` or `test`).
Cross-project access is rejected with a `403` error.

## Best practices

- Store the key in an environment variable (e.g. `ETHEN_GATEWAY_KEY`).
- Never commit the raw key to source control.
- Use separate keys for development and production environments.
- Rotate keys periodically using the API Keys dashboard.

## See also

- [Gateway overview](/docs/gateway/overview)
- [Quickstart](/docs/gateway/quickstart)