# Authentication

> Call the API with an sk_live_ API key or a dna_at_ OAuth access token. How to get each, OAuth 2.1 with PKCE step by step, every scope, and what a refusal looks like.

Source: https://docs.dissolve.email/authentication

Every `/v1` request carries one credential in the `Authorization` header:

```http
Authorization: Bearer sk_live_...
```

| Credential | Prefix | Who it is for | Scopes | Plans |
|---|---|---|---|---|
| API key | `sk_live_` | Your own scripts, tests, CI and agents | Every scope | Pro and Business |
| OAuth access token | `dna_at_` | Apps and agents acting for someone else | What the person approved | Every plan |

Both prefixes are contracts: keys and tokens issued by destroy.network keep working and are accepted for good. A credential is checked on every request, so a revoked key or a downgraded plan takes effect at once.

## API keys

An API key belongs to your account and can do anything you can do through the API. Make one in the app under [API keys](https://app.dissolve.email/dashboard/api-keys), or with the CLI's browser sign-in (`dna auth login`, see [CLI](/cli)). The key is shown once; only its first characters are kept for display. Pro accounts may hold 5 keys and Business 10. [API keys](/api-keys) covers making, listing and revoking them.

```bash cURL
curl https://api.dissolve.email/v1/me \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

// Reads DISSOLVE_API_KEY, then the old DESTROY_NETWORK_API_KEY
const client = new Dissolve();
console.log(await client.v1.me());
```

```python Python
import os, requests

response = requests.get(
    "https://api.dissolve.email/v1/me",
    headers={"Authorization": f"Bearer {os.environ['DISSOLVE_API_KEY']}"},
)
print(response.json())
```

> [!WARNING] Keep keys secret
> A key reads every inbox and vault entry on the account. Keep it in an environment variable or a secret store, never in code you commit or ship to a browser. Revoke a leaked key in the app straight away.

A Free account has no API keys: a request with one answers `403 plan_required`. Free accounts can still use the API through an OAuth connection, such as the [MCP server](/mcp).

## OAuth 2.1 with PKCE

Use OAuth when your app or agent acts for people who have their own dissolve.email accounts. They approve your app on app.dissolve.email, choose what it may do, and can remove it at any time under Connected apps. You never see their password or an API key.

The server is standard OAuth 2.1: authorization code with PKCE (`S256` only), refresh token rotation, dynamic client registration and RFC 8414 and RFC 9728 discovery. Clients that speak MCP find all of it by themselves.

| | |
|---|---|
| Issuer | `https://api.dissolve.email` |
| Discovery | `https://api.dissolve.email/.well-known/oauth-authorization-server` |
| Protected resource | `https://api.dissolve.email/.well-known/oauth-protected-resource` |
| Access token | `dna_at_...`, one hour |
| Refresh token | `dna_rt_...`, 30 days from its last use, one use each |
| Authorization code | `dna_ac_...`, 60 seconds, one use |

### 1. Register your app

Public clients (a CLI, a desktop or browser app, an agent) register themselves. No secret is issued; PKCE protects the code instead. Ten registrations a minute and 20 a day are allowed from one address.

`POST /oauth/register`

```bash cURL
curl -X POST https://api.dissolve.email/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My agent", "redirect_uris": ["http://localhost:8976/callback"]}'
```

```json
{
  "client_id": "dyn_4hT9kQ2mXv7pLr1ZcN8bW3sY",
  "client_name": "My agent",
  "redirect_uris": ["http://localhost:8976/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

A self-registered app is labelled unverified on the consent page, with the host it redirects to, and an unverified app asking for vault access needs a second confirmation. Confidential clients with a `dna_cs_` secret are issued by us for partner apps: write to support@dissolve.email.

### 2. Send the person to authorize

Make a random `code_verifier` (43 to 128 characters), hash it with SHA-256 and encode it as base64url without padding: that is the `code_challenge`. Keep the verifier and a random `state` for the next step.

`GET /oauth/authorize`

```http
GET https://api.dissolve.email/oauth/authorize
  ?response_type=code
  &client_id=dyn_4hT9kQ2mXv7pLr1ZcN8bW3sY
  &redirect_uri=http://localhost:8976/callback
  &scope=profile inboxes:read inboxes:write messages:read
  &state=af0ifjsldkj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
```

The person signs in if they need to, sees your app's name and the scopes in plain words, and approves or declines. The browser then returns to your redirect address with `code`, `state` and `iss=https://api.dissolve.email`. Check that `state` is the one you sent. A refusal comes back as `error=access_denied`.

Pass `resource` to bind the token to one API: `https://api.dissolve.email/v1` for the REST API, or `https://mcp.dissolve.email/mcp-oauth` for the MCP server. A token bound to one is refused by the other.

### 3. Exchange the code

`POST /oauth/token`

```bash cURL
curl -X POST https://api.dissolve.email/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=dyn_4hT9kQ2mXv7pLr1ZcN8bW3sY \
  -d code=dna_ac_... \
  -d redirect_uri=http://localhost:8976/callback \
  -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
```

```ts TypeScript
import { authorizeUrl, createPkce, exchangeCode, parseRedirect, withRefresh } from '@dissolve-email/sdk/oauth';

const pkce = await createPkce();
const { url, state } = authorizeUrl({
  clientId,
  redirectUri,
  scopes: ['profile', 'inboxes:read', 'inboxes:write', 'messages:read'],
  codeChallenge: pkce.challenge,
});
// Send the browser to url. When it comes back to redirectUri:
const code = parseRedirect(location.href, state);
const tokens = await exchangeCode({ clientId, code, redirectUri, codeVerifier: pkce.verifier });
const token = withRefresh(tokens, { clientId, onRefresh: save });
```

```json
{
  "access_token": "dna_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dna_rt_...",
  "scope": "profile inboxes:read inboxes:write messages:read"
}
```

Send the access token as `Authorization: Bearer dna_at_...` to `/v1`. The SDK's `withRefresh` swaps it for a new one before it expires.

### 4. Refresh and revoke

When the access token runs out, trade the refresh token for a new pair at the same endpoint with `grant_type=refresh_token`. Each refresh token works once: store the new one every time. A refresh also ends the access tokens issued before it. If a used refresh token is presented again, the server takes it as stolen and ends the whole connection; the person has to approve the app again.

To sign out, revoke either token: every token of that connection stops working.

`POST /oauth/revoke`

```bash cURL
curl -X POST https://api.dissolve.email/oauth/revoke \
  -d client_id=dyn_4hT9kQ2mXv7pLr1ZcN8bW3sY \
  -d token=dna_rt_...
```

## Scopes

A scope is what a connection may do. Ask for the fewest you need; the consent page lists each one in the words below. A `:write` scope includes its `:read`. API keys have every scope. When an MCP client asks for none, it gets the ones marked MCP default.

| Scope | Consent page says | What it allows | MCP default | Endpoints |
|---|---|---|---|---|
| `profile` | See your account | Your account id, plan and usage. | yes | 1 |
| `email` | See your email address | The address you sign in with. | no | 0 |
| `inboxes:read` | See your inboxes | Addresses, aliases and when they expire. | yes | 4 |
| `inboxes:write` | Manage your inboxes | Create, extend, rename and delete inboxes and aliases. | yes | 6 |
| `messages:read` | Read your email | Messages, attachments and verification codes in your inboxes. | yes | 11 |
| `messages:write` | Change your email | Delete and label messages. | yes | 2 |
| `identities:read` | See your agent identities | Addresses, personas and saved passwords. | yes | 2 |
| `identities:write` | Manage your agent identities | Create, extend and delete identities. | yes | 3 |
| `vault:read` | See your vault | Saved credentials, passwords included. | no | 2 |
| `vault:write` | Change your vault | Add, edit and delete saved credentials. | no | 3 |
| `webhooks:manage` | Manage your webhooks | Create, change and delete webhook endpoints. | no | 5 |
| `rules:manage` | Manage your rules | Inbox rules, labels and templates. | no | 10 |

Every operation in the [API reference](/reference) names the scope it needs. Scope names never change.

## Checking a credential

`GET /v1/connection`

Needs no scope, so it is the safe first call for any credential: it says what kind it is, which scopes it carries, its per-minute rate and the resource an OAuth token was issued for.

```json
{ "kind": "mcp", "clientId": "dyn_4hT9kQ2mXv7pLr1ZcN8bW3sY", "scopes": ["profile", "inboxes:read", "messages:read"], "requestsPerMinute": 30, "resource": "https://api.dissolve.email/v1" }
```

`kind` is `user` or `cli` for an API key (made in the app, or by `dna auth login`) and `mcp` or `app` for an OAuth connection.

## When a credential is refused

| Status | `error.code` | Means | Do |
|---|---|---|---|
| 401 | `unauthorized` | No `Authorization: Bearer` header, or an unknown kind of token | Send one |
| 401 | `invalid_api_key` | The key is wrong or was revoked | Make a new key |
| 401 | `invalid_token` | The access token expired, was revoked or the connection was removed | Refresh it, or start the flow again |
| 403 | `plan_required` | API keys need Pro or Business | Upgrade, or connect through OAuth |
| 403 | `insufficient_scope` | The connection was not given the scope this endpoint needs | Ask for the scope and have the person approve again |

A 401 carries `WWW-Authenticate: Bearer realm="dissolve", resource_metadata="https://api.dissolve.email/.well-known/oauth-protected-resource"`, which is how an OAuth client finds the server. A 403 for a missing scope names it:

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "This connection was not given \"inboxes:write\" (manage your inboxes). Reconnect the app and approve it.",
    "details": { "scope": "inboxes:write" }
  }
}
```

## Signed-in sessions

The app at app.dissolve.email signs people in with a code sent by email and keeps them signed in with a cookie. A few routes answer only to that session, never to a key or a token: making and revoking API keys, billing, teams and the shared inbox room. They are listed on [API keys](/api-keys) and [Teams](/teams) for completeness; build on `/v1` instead.
