Authentication
How to authenticate to the Dock workspace API. Three token types, four scopes, document-scoped tokens, and where to create a key.
Every request to the workspace carries an API key. The REST API and the MCP server both read it from the x-api-key header; the CLI stores it for you after agentdock login.
curl https://app.agentdock.ai/api/d \
-H "x-api-key: ak_usr_YOUR_TOKEN"A key's prefix tells you what it can reach. There are three types.
| Prefix | Type | Reaches |
|---|---|---|
ak_usr_ | User | One user's documents, folders, citations, and prompts |
ak_org_ | Organization | The organization's own API surfaces, independent of any single user (document-workspace access coming soon) |
ak_doc_ | Document | A single document it is bound to, and nothing else |
- User tokens (
ak_usr_) are the common case for an individual driving their own workspace from a CLI or a script. The key stops working if the owning account is removed. - Organization tokens (
ak_org_) belong to the organization rather than a person, so they keep working through changes in who is on the team. Document-workspace access for org tokens is coming soon; until it ships, use a user token (ak_usr_) for document automation and CI. - Document tokens (
ak_doc_) are the tightest scope. Each one is bound at creation to a specific document and can only touch that document. Hand one to an agent or a collaborator who should work on exactly one draft and nothing else.
A document token is not a general key with a filter applied; it is bound to one document ID when it is minted, and the server enforces that binding on every request. A token with no document attached is rejected. This is what makes it safe to pass a document token to a narrow task: the worst it can do is touch the one document it was issued for.
Independent of its type, a key carries a set of scopes that decide which verbs it can use.
| Scope | Allows |
|---|---|
read | List and read documents, versions, citations, and prompts |
write | Create, edit, and delete content; propose and resolve suggestions |
publish | Publish a document to a public URL and unpublish it |
delete | Delete documents and folders |
Scopes are additive. A read-only key cannot write or publish; a key with read and write but not publish can edit a draft all day and never make it public. Grant the narrowest set the job needs. A request that uses a verb outside the key's scopes is rejected.
Create and manage keys in the dashboard, where you choose the type, the scopes, and (for a document token) the document to bind it to. Treat a key like a password: it is shown once at creation, so store it somewhere safe. If a key leaks, revoke it in the dashboard and mint a new one.
The CLI keeps your key in a local config file after agentdock login. Run agentdock token to see which key is in use, and agentdock logout to clear it locally. Clearing it locally does not revoke the key server-side; revoke from the dashboard if you need the key itself to stop working.
- Getting Started: your first published page
- REST API Reference: every route and its required scope
- MCP Server Setup: authenticating an MCP client