Get started
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.
Every /v1 request carries one credential in the Authorization header:
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, or with the CLI's browser sign-in (dna auth login, see 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 covers making, listing and revoking them.
curl https://api.dissolve.email/v1/me \
-H "Authorization: Bearer $DISSOLVE_API_KEY"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());import os, requests
response = requests.get(
"https://api.dissolve.email/v1/me",
headers={"Authorization": f"Bearer {os.environ['DISSOLVE_API_KEY']}"},
)
print(response.json())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.
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
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"]}'{
"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.
/oauth/authorize
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=S256The 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
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_wW1gFWFOEjXkimport { 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 });{
"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
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 names the scope it needs. Scope names never change.
Checking a credential
GET/v1/connectionAny 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.
{ "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:
{
"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 and Teams for completeness; build on /v1 instead.
Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown