API v1
Authentication
Bearer tokens, scopes, and security model.
Protected /api/v1 routes require a valid BennyBooks API token in the Authorization header. Public discovery (OpenAPI, ontology, /llms.txt, /developers) needs no token.
http
Authorization: Bearer bb_live_<token>Token format
- Prefix: bb_live_
- Stored as SHA-256 hash — plaintext shown once at creation
- Org-scoped — tied to the Clerk organization active when created
- Revocable from Settings → MCP access
Scopes
| Scope | Access |
|---|---|
| read | All GET endpoints |
| propose-write | POST and PUT write endpoints (includes read) |
Public endpoints
GET /openapi.json, GET /api/v1/ontology.jsonld, GET /api/v1/ontology/context.jsonld, /llms.txt, /agents.txt, /skill.md, and /developers are public (no token).
Pro plan
When billing enforcement is enabled (BILLING_ENFORCEMENT=true), propose-write tokens require a Pro subscription.