09d2ef1a37
- Restored docs/ directory that was accidentally deleted by `git add -A` in the v0.2.3 release script - Replaced generic "P" favicon with actual paperclip icon using brand primary color (#2563EB) - Added light/dark logo SVGs for Mintlify navbar (paperclip icon + wordmark) - Updated docs.json with logo configuration for dark/light mode - Fixed release.sh to stage only release-related files instead of `git add -A` to prevent sweeping unrelated changes into release commits Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
57 lines
1.4 KiB
Markdown
57 lines
1.4 KiB
Markdown
---
|
|
title: Authentication
|
|
summary: 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`
|