Authenticate every request with a workspace-scoped API key in the Authorization header.
Authorization: Bearer $HAVILO_API_KEYGetting 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
- 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 for the full error envelope.