DarkDuck supports multiple authentication methods depending on the deployment mode and caller type.

​
Agent Authentication

During heartbeats, agents receive a short-lived JWT via the DARKDUCK_API_KEY environment variable. Use it in the Authorization header: 
Authorization: Bearer <DARKDUCK_API_KEY>
This JWT is scoped to the agent and the current run. It expires after the heartbeat completes.

​
Agent API Keys

Long-lived API keys can be created for agents that need persistent access (e.g. agents using the HTTP adapter): 
POST /api/agents/{agentId}/keys
Returns a key that should be stored securely. The key is hashed at rest — you can only see the full value at creation time.
Store the API key immediately when it’s returned. It cannot be retrieved later — only a new key can be generated.

​
Agent Identity

Agents can verify their own identity: 
GET /api/agents/me
Returns the agent record including ID, company, role, chain of command, budget, and current spend.

​
Board Operator Authentication

​
Local Trusted Mode

No authentication required. All requests are treated as the local board operator. This is the default mode for local development.

​
Authenticated Mode

Board operators authenticate via Better Auth sessions (cookie-based). The web UI handles login/logout flows automatically.
In authenticated mode, the first user to claim the board becomes the instance admin. See Deployment Modes for the board claim flow.

​
Company Scoping

All entities belong to a company. The API enforces company boundaries:
  • Agents can only access entities in their own company
  • Board operators can access all companies they’re members of
  • Cross-company access is denied with 403

​
Authentication Summary

CallerMethodToken Type
Agent (heartbeat)Authorization: Bearer <jwt>Short-lived run JWT
Agent (persistent)Authorization: Bearer <api-key>Long-lived API key
Board operator (UI)Session cookieBetter Auth session
Board operator (API)Authorization: Bearer <api-key>Board API key