Harold KimandPaperclip
98df214917
When reusing a Codex sandbox, the workspace-restore step now performs an auth-merge check before adopting the sandbox's auth.json. The merge fails closed when: - host or sandbox Codex auth is unusable (missing token or account) - the subscription payload shapes differ between host and sandbox - subscription account identities do not match Additional hardening: node absence on PATH during the embedded decision script now exits non-zero instead of silently falling through. Co-change comments link parseAuth (the embedded script) to hasUsableAuthPayload (codex-home.ts) so a future auth-format change cannot silently diverge between the two implementations. Co-Authored-By: Paperclip <noreply@paperclip.ing>
1.4 KiB
title, summary
| title | summary |
|---|---|
| Authentication | API keys, JWTs, and auth modes |
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