Skip to content
docs
Browse the docsAuthentication

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:

HTTP
Authorization: Bearer sk_live_...
CredentialPrefixWho it is forScopesPlans
API keysk_live_Your own scripts, tests, CI and agentsEvery scopePro and Business
OAuth access tokendna_at_Apps and agents acting for someone elseWhat the person approvedEvery 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"

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.

Issuerhttps://api.dissolve.email
Discoveryhttps://api.dissolve.email/.well-known/oauth-authorization-server
Protected resourcehttps://api.dissolve.email/.well-known/oauth-protected-resource
Access tokendna_at_..., one hour
Refresh tokendna_rt_..., 30 days from its last use, one use each
Authorization codedna_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
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
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
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
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.

ScopeConsent page saysWhat it allowsMCP defaultEndpoints
profileSee your accountYour account id, plan and usage.yes1
emailSee your email addressThe address you sign in with.no0
inboxes:readSee your inboxesAddresses, aliases and when they expire.yes4
inboxes:writeManage your inboxesCreate, extend, rename and delete inboxes and aliases.yes6
messages:readRead your emailMessages, attachments and verification codes in your inboxes.yes11
messages:writeChange your emailDelete and label messages.yes2
identities:readSee your agent identitiesAddresses, personas and saved passwords.yes2
identities:writeManage your agent identitiesCreate, extend and delete identities.yes3
vault:readSee your vaultSaved credentials, passwords included.no2
vault:writeChange your vaultAdd, edit and delete saved credentials.no3
webhooks:manageManage your webhooksCreate, change and delete webhook endpoints.no5
rules:manageManage your rulesInbox rules, labels and templates.no10

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.

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

Statuserror.codeMeansDo
401unauthorizedNo Authorization: Bearer header, or an unknown kind of tokenSend one
401invalid_api_keyThe key is wrong or was revokedMake a new key
401invalid_tokenThe access token expired, was revoked or the connection was removedRefresh it, or start the flow again
403plan_requiredAPI keys need Pro or BusinessUpgrade, or connect through OAuth
403insufficient_scopeThe connection was not given the scope this endpoint needsAsk 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 and Teams for completeness; build on /v1 instead.

Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown