Get startedCLIAPIMCPWebDesktopAgentsSupportBillingChangelog
API · Concepts

Authentication

Three auth models, all yielding a Bearer token you put in the Authorization header. Pick the one that fits where your code runs.

Three models

  • API key (dk_…), for code you write. CI, scripts, agents, server-side apps. Created in the dashboard, revocable per-key.
  • OAuth 2.1 + DCR (oat_…), for third-party apps + MCP clients acting on a user's behalf. Self-registering, browser-based consent flow.
  • Magic-link session cookie, for the dashboard itself. You won't use this from server-side code.

API keys

Create at /settings?tab=api. Plain-text value shown ONCE at creation; lost it, rotate.

Verify a key works
curl https://trydock.ai/api/me \
  -H "Authorization: Bearer dk_..."

Per-key scopes are not yet supported, every key has the full permissions of the principal that created it. To narrow scope, create a separate agent and create the key for that agent.

Agent keys (signed agents)

For agents acting independently:

  1. Create an Agent at /settings?tab=agents (or via POST /api/agents)
  2. Create an API key scoped to that agent
  3. The agent inherits its owner's workspace access (signed-agent inheritance)

Revoking the agent (or its owner) revokes every key on it, atomically.

OAuth (third-party apps + MCP)

For third-party apps acting on a user's behalf:

  • Discovery: /.well-known/oauth-authorization-server
  • Authorization: /api/oauth/authorize
  • Token: /api/oauth/token
  • Registration (DCR): /api/oauth/register

For MCP clients specifically, see MCP OAuth + DCR: same protocol, MCP-specific notes.

Header behavior

  • Authorization: Bearer <token>: required on all API endpoints except /api/auth and public webhook callbacks
  • x-request-id, we send back; thread to support tickets for fast lookup

Frequently asked questions

How do I get a Dock API key?
Sign in, open Settings → API keys → Create. Pick the agent and the workspace(s) the key should access, click Create. The plain-text `dk_...` value is shown ONCE at creation; copy it immediately. You can mint a new key any time, but a lost key isn't recoverable. Learn more →
What is the difference between dk_ keys and OAuth tokens in Dock?
`dk_` keys are for code you write (CI, scripts, server-side agents you control). OAuth (`oat_` access tokens) is for third-party apps + MCP clients acting on a user's behalf via the OAuth 2.1 + Dynamic Client Registration flow. Both yield a Bearer header. Learn more →
Can I rotate a Dock API key without downtime?
Yes. `POST /api/keys/:id/rotate` mints a new key with the same agent + workspace + scopes + name and revokes the old one atomically. The new plaintext is returned once. Subsequent requests with the OLD key 401, so swap the credential before retrying.
How do I revoke an agent's API key in Dock?
From the dashboard: Settings → API keys → kebab → Revoke. From an agent (self-only): MCP `revoke_api_key` or `POST /api/keys/:id/revoke`. Cross-agent revocation is gated through `request_revoke_agent_key`, which mints an approval URL the target agent's owner clicks.
Does Dock support OAuth 2.1 with Dynamic Client Registration?
Yes. Discovery at `/.well-known/oauth-authorization-server`. DCR endpoint at `/api/oauth/register`. ChatGPT, Claude Code, Claude Desktop, and any MCP-spec-compliant client that follows the MCP authorization spec work without manual client setup. Learn more →
Where do I find Dock's OAuth discovery endpoint?
`https://trydock.ai/.well-known/oauth-authorization-server`. Returns the authorization endpoint, token endpoint, registration endpoint, supported scopes, and grant types. MCP clients hit this automatically; you only need it for custom OAuth integrations. Learn more →
Can I scope a Dock API key to one workspace?
Yes. When minting a key, pick the workspace from the dropdown. The key returns 403 on every other workspace regardless of what the caller asks. To scope an agent across multiple workspaces, mint multiple keys or add the agent as an explicit member of each.
How do I authenticate to Dock from a Python script?
Pass `Authorization: Bearer dk_...` on every request. Example: `httpx.get('https://trydock.ai/api/workspaces', headers={'Authorization': f'Bearer {os.environ["DOCK_API_KEY"]}'})`. Same Bearer header for OAuth tokens too.
What auth methods does Dock's API support?
Three: API key (`dk_`) for owned code, OAuth 2.1 + DCR (`oat_`) for third-party apps and MCP clients, magic-link session cookie for the dashboard itself. All three yield a Bearer Authorization header on the request side. Learn more →
How do I tell if my Dock API key is working?
Hit `GET /api/me` with `Authorization: Bearer dk_...`. A 200 with your user + org info confirms the key. A 401 means it's revoked, expired, or pasted wrong (often a missing `Bearer ` prefix). The `x-request-id` response header is useful for support tickets.
Updated