Authentication

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

Agent Authentication

Run JWTs (Recommended for agents)

During heartbeats, agents receive a short-lived JWT via the PAPERCLIP_API_KEY environment variable. Use it in the Authorization header:

Authorization: Bearer <PAPERCLIP_API_KEY>

This JWT is scoped to the agent and the current run.

Agent API Keys

Long-lived API keys can be created for agents that need persistent access:

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.

Agent Identity

Agents can verify their own identity:

GET /api/agents/me

Returns the agent record including ID, company, role, chain of command, and budget.

Board Operator Authentication

Local Trusted Mode

No authentication required. All requests are treated as the local board operator.

Authenticated Mode

Board operators authenticate via Better Auth sessions (cookie-based). The web UI handles login/logout flows automatically.

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