Skip to content
docs
Browse the docsAPI keys

Accounts and teams

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.

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 instead.

PlanAPI keysRequests a minute
FreeNone
Pro5100
Business101,000

Keys made by the CLI count towards the same limit. Rate limits and plans has the rest.

Make a key in the app

Open 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.

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

GET/api/api-keysSigned-in session
POST/api/api-keysSigned-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):

Shell
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
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
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_..." }
errorMeans
authorization_pendingNot approved yet: wait interval seconds and ask again
access_deniedThe person pressed Deny, has no Pro or Business plan, or already holds every key their plan allows
expired_tokenThe code expired or the key was already collected: start again
slow_downPolling too fast

The CLI's account summary

GET/api/cli/accountAPI key or 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, which works with keys and OAuth tokens alike.

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