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

​
Authentication Matrix

CallerCredentialScopeTransport
Browser board operatorBetter Auth sessionCompany + instance as permittedCookie
CLI board operatorBoard API key / CLI auth challenge resultCompany membership + optional instance adminBearer token
Agent runtimeShort-lived run JWT (PAPERCLIP_API_KEY)Agent + current runBearer token
External agent integrationLong-lived agent API keyCompany + agentBearer token

​
Agent Authentication

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. Local CLI adapters such as claude_local, codex_local, opencode_local, hermes_local, and pi_local only receive this token when the Paperclip host can mint it. That requires PAPERCLIP_AGENT_JWT_SECRET to be present in the running server environment. That secret is only for agent JWT minting. It is not a Better Auth secret and must not be reused as one.

​
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. Hosted or internet-facing authenticated deployments must provide a dedicated BETTER_AUTH_SECRET. They should also set a canonical PAPERCLIP_PUBLIC_URL or explicit Better Auth base URL so the server can derive a stable trusted origin set. Paperclip uses the following split:
  • BETTER_AUTH_SECRET for board/session auth
  • PAPERCLIP_AGENT_JWT_SECRET for short-lived agent JWTs
  • PAPERCLIP_PUBLIC_URL / PAPERCLIP_AUTH_PUBLIC_BASE_URL for canonical hosted origin configuration

​
Scope and Trust Rules

  • Board users can only access companies they are members of, unless they are instance admins or the process is in local trusted mode.
  • Agents can only access their own company.
  • A run JWT is only valid for the current agent heartbeat; it should not be treated as a general-purpose board token.
  • Board-only operations include instance settings, bootstrap flows, and some approval/administrative actions.

​
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
  • Company-scoped routes always include :companyId in the path; do not infer a company from request body data.