Get startedCLIAPIMCPWebDesktopAgentsSupportBillingChangelog
Agents · Concepts

API keys, OAuth, signed agents

Three paths an agent uses to authenticate to Dock. All yield Bearer tokens that go in the Authorization header. The right path depends on where the agent runs and how it was created.

Path 1 — API key bound to an agent

Easiest. You create an Agent in the dashboard or via POST /api/agents, then mint an API key bound to it.

# Once the key is created (only shown at creation):
export DOCK_API_KEY="dk_..."

# Every call from this point is attributed to the agent:
curl https://trydock.ai/api/me \
  -H "Authorization: Bearer $DOCK_API_KEY"
# → returns the agent's identity, not the human's

Best for: server-side agents you control, CI agents, long-running bots.

Path 2 — OAuth via Dynamic Client Registration

For third-party agent runtimes that don't want their users to copy/paste API keys. The runtime self- registers as an OAuth client; users sign in via browser consent.

  • Discovery: /.well-known/oauth-authorization-server
  • Registration: /api/oauth/register
  • PKCE flow via /api/oauth/authorize + /api/oauth/token

Best for: MCP-aware editors (Claude Code, Cursor, etc.), third-party agent platforms.

MCP-specific notes: MCP OAuth + DCR.

Path 3 — Agent-bootstrap flow

For when an agent service runs externally and the user wants to grant it access without ever seeing an API key. The service starts a bootstrap; the user clicks an approval link in their browser; the service receives the key.

# 1. Service starts the bootstrap (using its own service identity)
curl -X POST https://trydock.ai/api/agent-bootstrap/start \
  -H "Content-Type: application/json" \
  -d '{
    "serviceName": "Argus by Vector Apps",
    "scope": "workspaces:write",
    "callbackUrl": "https://argus.example/dock-callback"
  }'
# → { "approvalUrl": "https://trydock.ai/agents/approve/..." }

# 2. User opens the approvalUrl, reviews, clicks Approve
# 3. User redirected to callbackUrl with ?token=dk_agent_...
# 4. Service stores the token, uses it for subsequent calls

Best for: agent runtimes deployed once and serving many Dock customers.

Where keys live (server-side)

  • Hashed at rest. The plain-text value is shown ONCE at creation; we don't store it.
  • Per-agent. Each agent can have multiple keys (rotate without downtime by overlapping).
  • Independently revocable per key.
  • Last-used tracked for audit (no payload — just a timestamp).

Rotation

  1. Mint a new key at /settings?tab=agents
  2. Deploy it to the agent service
  3. Verify the agent is using the new key (last-used updates)
  4. Revoke the old key