Keys, workspaces and sign-in
How keys decide what a call may reach and do, how to pick a workspace, and how AI assistants sign in.
This page explains what a key can reach and do, how to choose a workspace on each call, and how sign-in replaces keys for AI assistants.
Every call needs credentials in the Authorization header:
curl https://api.done.com/v1/me -H "Authorization: Bearer done_live_..."What a key is
Make a key in done. under Settings, API keys. The secret is shown once. You can revoke a key there at any time. Keys cannot be made through the API.
A key has four settings:
| Setting | What it decides |
|---|---|
| Reach | Which workspaces the key can act on: workspace (exactly one), workspaces (a chosen set) or org (every workspace in the organization, including ones made later). |
| Permission | What the key may do: read, spend or full. |
| Daily credit cap | The most credits this key may use in one UTC day. No cap is also possible. |
| Expiry | When the key stops working. A key can also have no expiry. |
GET /me shows all four for the key you are calling with, plus credits_used_today and the api_version the key is pinned to.
A key that is missing, wrong, revoked or expired is refused with a 401. The code says which: key_missing, key_invalid, key_revoked or key_expired.
Permissions
Every operation names the permission it needs. A permission includes the ones before it.
| Permission | What it allows |
|---|---|
read | Looking: reading workspaces, people, runs, results and campaigns. |
spend | Everything in read, plus paid work such as scoring and research. |
full | Everything in spend, plus anything that changes setup or can reach a person on LinkedIn. |
A key that asks for more than it has is refused with 403 permission_too_low. The fix says which permission the call needs.
Choosing a workspace
A workspace is one set of customer profiles, people, campaigns and sending accounts.
- A key that reaches exactly one workspace may leave out
Done-Workspace. That workspace is used. - A key that reaches more than one must send
Done-Workspace: ws_...on every call. Without it, the call is refused with 400workspace_required. - A workspace the key does not reach is refused with 403
workspace_not_in_reach, whatever the key's reach.
Find the ids on GET /me under reach.workspaces, or with GET /workspaces.
curl https://api.done.com/v1/scoring_runs \
-H "Authorization: Bearer $DONE_API_KEY" \
-H "Done-Workspace: ws_4fQk2LmZ"Looking up an object by id never leaks across workspaces. An id from another workspace answers not_found, the same as an id that does not exist.
The daily credit cap
Each key can carry a cap on the credits it may use per UTC day. Paid work counts against it, and a scout run is bounded by it too. Past the cap, paid calls are refused with 403 daily_credit_cap_reached. Check daily_credit_cap and credits_used_today on GET /me. See Credits and costs.
Test keys
A key that starts with done_test_ is a test key.
- It works only inside your organization's test workspace. That workspace is made when your organization's first test key is made.
- The test workspace is kept apart from every real workspace and cannot hold real sending accounts. Nothing a test key creates can ever send for real.
- Test work charges no credits and calls nothing outside done.
- An operation with a test version returns realistic sample answers. One without answers 403
not_available_in_test_mode.
GET /me shows "test": true for a test key.
Sign-in for AI assistants
AI assistants and the done. MCP server do not use pasted keys. The person signs in with done. instead, approves access in a browser, and picks the workspaces the assistant may touch.
Sign-in uses OAuth 2 with the authorization code flow:
| Part | Address |
|---|---|
| Authorize | https://app.done.com/oauth/authorize |
| Token and refresh | https://api.done.com/oauth/token |
The scopes are named like permissions:
| Scope | What it allows |
|---|---|
read | See your workspaces, people, campaigns and results. |
spend | Read, and do paid work such as scoring and research. |
full | Read, spend, and send or change campaigns and replies. |
Sends made through sign-in are recorded as API sends, never as the signed-in person's own reply, so sending hours and limits always apply. See AI assistants and MCP.
Organization keys
Two operations manage keys: GET /keys lists the organization's keys and DELETE /keys/{id} revokes one. Only a key with full permission and org reach, made by an organization admin, can call them. Secrets are never returned.