Authentication
Clerk session tokens, acervo tokens, and rate limits
Clerk session token (Bearer)
Every authenticated route expects a Clerk session JWT:
Authorization: Bearer <clerk-session-token>The token carries the user identity and, when a team is active, the organization (orgId) and the user's org role. All document queries are scoped to the active tenant: the organization when one is selected, otherwise the user's personal workspace.
curl -H "Authorization: Bearer $CLERK_TOKEN" \
https://jatoba-web3-production.up.railway.app/api/documentsOrganization roles (RBAC)
Inside an organization, four roles apply:
| Role | Upload / capture / publish | Delete team docs | Manage team | Manage settings |
|---|---|---|---|---|
owner | ✓ | ✓ | ✓ | ✓ |
admin | ✓ | ✓ | ✓ | ✓ |
editor | ✓ | — | — | — |
reader | — | — | — | — |
Personal workspaces (no active org) are unrestricted for their owner.
Acervo token
The public archive feed (GET /api/public/acervo) is authorized by a per-tenant acervo token instead of a Clerk session — the token both names the tenant and grants read access. Generate it with POST /api/settings/acervo-token and send it as a Bearer credential.
Public routes
No credentials needed: GET /health, GET /api/onchain/info, GET /api/public/verify, GET /api/public/documents/:serial, the share/access routes (/share/:token, /access/...), and the Clerk webhook.
Rate limits
- Global: 120 requests/minute per user (or per IP when unauthenticated)
- Upload, IPFS import, timestamp: 10/minute
- Web capture: 5/minute
- Public verification: 30/minute · Acervo feed: 60/minute
CORS
Browser origins must be allow-listed in the server's ALLOWED_ORIGINS configuration. Server-to-server requests (no Origin header) always pass.