# Authentication

> How Distilled API keys work: the bearer header, the key format, revoking a key, and the scopes that decide what each key may do.

Send your key in the `Authorization` header of every request, as `Bearer dk_live_…`. Keys look like `dk_live_` followed by a 16-character key id, an underscore and a 43-character secret. We keep only a hash of the secret, so a lost key cannot be recovered. Revoke it under [Developers → API keys](https://app.distilled.cx/developers/api-keys) and create another. A revoked key stops working within 30 seconds.

## Scopes

Each key carries the scopes picked when it was created, all of them by default. Every route needs one, except `/v1/me` and `/v1/status`, which any key may call.

| Scope | Allows |
| --- | --- |
| `phones:read` | Listing phones, the catalog, apps, installs and proxies, and reading egress |
| `phones:write` | Allocating, releasing, starting, stopping and restarting phones, installing apps, and managing proxies and where phones connect |
| `control:write` | Leasing a phone, taking screenshots and reading its screen, and acting on it |
| `runs:read` | Listing runs, reading their steps and screenshots, following their events, reading usage |
| `runs:write` | Starting, stopping and resuming runs, and managing secrets |
| `skills:read` | Listing and reading skills |
| `skills:write` | Creating, changing, enabling, disabling and deleting skills |
| `billing:read` | Reading the balance and its entries |
| `billing:write` | Starting a top-up by card |

A missing or unknown key gets `401 unauthorized`. A valid key without the scope a route needs gets `403 forbidden`, and the detail names the scope.

Source: https://distilled.cx/docs/authentication/