# API keys

> Make, list and revoke sk_live_ API keys in the app or with the CLI's browser sign-in. Limits per plan, how keys are stored, and the device flow the CLI uses.

Source: https://docs.dissolve.email/api-keys

An API key (`sk_live_...`) is a credential for your own account with every scope. Use it in scripts, test suites, CI and agents you run yourself. When you build something other people sign in to, use [OAuth](/authentication#oauth-2-1-with-pkce) instead.

| Plan | API keys | Requests a minute |
|---|---|---|
| Free | None | |
| Pro | 5 | 100 |
| Business | 10 | 1,000 |

Keys made by the CLI count towards the same limit. [Rate limits and plans](/rate-limits) has the rest.

## Make a key in the app

Open [API keys](https://app.dissolve.email/dashboard/api-keys), give the key a name (what or where it is used, up to 100 characters) and press Create. The whole key is shown once; copy it then. Afterwards the app shows only its first 12 characters (`sk_live_xxxx`), its name and when it was last used.

> [!WARNING] Shown once, stored as a hash
> dissolve.email keeps only a hash of the key, so a lost key cannot be shown again. Make a new one and revoke the old.

Managing keys takes the signed-in session from the app, never another key. These are the routes the app calls:

`GET /api/api-keys` (signed-in session)

`POST /api/api-keys` (signed-in session)

`DELETE /api/api-keys/{id}` (signed-in session)

Revoking is immediate: the next request with that key answers `401 invalid_api_key`. If you downgrade to Free, keys stop working (`403 plan_required`) until you upgrade again.

Apps and agents you connected with OAuth also hold a credential behind the scenes, but they are not listed here: find them, and remove them, under Connected apps in the app.

## Make a key with the CLI

`dna auth login` signs the CLI in through the browser and saves a new key to `~/.config/dissolve/config.json` (readable by you only):

```bash
dna auth login
dna auth status   # which key is in use, and where it came from
dna account       # plan, key count, identities and rate limit
```

Behind it is a device authorization flow you can use from your own tools too:

1. Ask for a code. The answer has a `user_code` to show the person, a `device_code` to keep, the page to open, and how long (600 seconds) and how often (every 5 seconds) to poll.
2. The person opens `https://app.dissolve.email/cli/auth?code=WDJB-MJHT`, signs in, checks the code matches and presses Approve. The page shows when, where and from which device the request came. Opening the page alone approves nothing.
3. Poll for the key. Until approval the answer is `400` with `authorization_pending`; then it is the key, once.

`POST /api/cli/device`

```bash cURL
curl -X POST https://api.dissolve.email/api/cli/device
```

```json
{
  "device_code": "dc_...",
  "user_code": "WDJB-MJHT",
  "verification_url": "https://app.dissolve.email/cli/auth",
  "expires_in": 600,
  "interval": 5
}
```

`POST /api/cli/token`

```bash cURL
curl -X POST https://api.dissolve.email/api/cli/token \
  -H "Content-Type: application/json" \
  -d '{"device_code": "dc_..."}'
```

```json
{ "api_key": "sk_live_..." }
```

| `error` | Means |
|---|---|
| `authorization_pending` | Not approved yet: wait `interval` seconds and ask again |
| `access_denied` | The person pressed Deny, has no Pro or Business plan, or already holds every key their plan allows |
| `expired_token` | The code expired or the key was already collected: start again |
| `slow_down` | Polling too fast |

## The CLI's account summary

`GET /api/cli/account` (API key or signed-in session)

Takes an API key (not an OAuth token) and answers with what `dna account` prints:

```json
{
  "user": { "email": "you@example.com", "tier": "pro", "status": "active" },
  "apiKeys": { "count": 2, "max": 5, "remaining": 3 },
  "rateLimit": { "requestsPerMinute": 100 },
  "agents": { "active": 1, "max": 10, "remaining": 9 },
  "plan": { "maxInboxes": 10, "inboxDurationMinutes": 30, "webhooks": true, "agentIdentities": true, "agentWaitTimeoutSeconds": 30 }
}
```

For anything else about a key, call [`GET /v1/connection`](/reference/account#describe-this-credential), which works with keys and OAuth tokens alike.
