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.
| 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 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:
/api/api-keysSigned-in session/api/api-keysSigned-in session/api/api-keys/{id}Signed-in sessionRevoking 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):
dna auth login
dna auth status # which key is in use, and where it came from
dna account # plan, key count, identities and rate limitBehind it is a device authorization flow you can use from your own tools too:
- Ask for a code. The answer has a
user_codeto show the person, adevice_codeto keep, the page to open, and how long (600 seconds) and how often (every 5 seconds) to poll. - 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. - Poll for the key. Until approval the answer is
400withauthorization_pending; then it is the key, once.
/api/cli/device
curl -X POST https://api.dissolve.email/api/cli/device{
"device_code": "dc_...",
"user_code": "WDJB-MJHT",
"verification_url": "https://app.dissolve.email/cli/auth",
"expires_in": 600,
"interval": 5
}/api/cli/token
curl -X POST https://api.dissolve.email/api/cli/token \
-H "Content-Type: application/json" \
-d '{"device_code": "dc_..."}'{ "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
/api/cli/accountAPI key or sessionTakes an API key (not an OAuth token) and answers with what dna account prints:
{
"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