# Authentication

Source: https://docs.havilo.ai/reference/ai-engine/authentication

Authenticate every request with a workspace-scoped API key in the `Authorization` header.

```txt
Authorization: Bearer $HAVILO_API_KEY
```

## Getting an API key

API keys are issued from your workspace settings under **Advanced**, where a workspace admin can generate a workspace-scoped key. If you can't find the option or run into trouble, contact your customer success manager.

## Key safety

> **Treat API keys like passwords**
>
> Anyone with the raw key can act as your workspace until the key is rotated.

* Store keys in a server-side secret manager or environment variable.
* Do not expose keys in browser code, mobile apps, client logs, or support tickets.
* Create separate keys for production and test integrations when available.
* Rotate keys if they are copied into chat, email, logs, or source control.

## Required Headers

| Header            | Required                     | Description                                |
| ----------------- | ---------------------------- | ------------------------------------------ |
| `Authorization`   | Yes                          | `Bearer $HAVILO_API_KEY`                   |
| `Content-Type`    | For request bodies           | Use `application/json`.                    |
| `Idempotency-Key` | Recommended for `POST /runs` | Makes create requests safe to retry.       |
| `X-Request-Id`    | Optional                     | Client request ID for support correlation. |

## Scopes

Keys are scoped to a workspace and may include only the capabilities your integration needs.

| Scope                        | Allows                                                                              |
| ---------------------------- | ----------------------------------------------------------------------------------- |
| `runs:create`                | Create runs with `POST /runs`.                                                      |
| `runs:read`                  | Read runs, events, event stream tokens, and entity resolution.                      |
| `runs:cancel`                | Cancel a run.                                                                       |
| `artifacts:read`             | Fetch artifact bodies.                                                              |
| `presets:dossier`            | Create `dossier` preset runs.                                                       |
| `config:xray`                | Use `config.xray` when enabled for the workspace.                                   |
| `config:global_search`       | Use `config.global_search` when enabled for the workspace.                          |
| `config:unlimited_transform` | Use `config.unlimited_transform` to lift the \~100-record cap on `transform` steps. |

## Authentication Errors

| HTTP status | Code                | Meaning                                                     |
| ----------- | ------------------- | ----------------------------------------------------------- |
| `401`       | `auth_missing`      | The `Authorization` header is missing or malformed.         |
| `401`       | `auth_invalid`      | The key is unknown or revoked.                              |
| `401`       | `auth_expired`      | The key has expired.                                        |
| `403`       | `forbidden_feature` | The key or workspace does not have the required capability. |

See [Errors](https://docs.havilo.ai/reference/ai-engine/errors.md) for the full error envelope.