Campbooks Public REST API (1.0.0)

Authentication

The API uses OAuth 2.0 client credentials. A credential acts as the user who created it, inside that user's workspace — there is no per-end-user authorization step.

1. In the app, go to Settings → API access and create a client. Pick the scopes it needs. The client secret is shown once — store it safely (it's hashed at rest and can be regenerated, not re-displayed).
2. Exchange the credentials for a short-lived bearer token (valid 2 hours) at POST /api/oauth/token. Always pass a scope parameter — a token requested with no scope can call nothing.
3. Send the token as Authorization: Bearer <token> on every /api/v1 request.

Scopes are a ceiling, not a grant of new power: a request must satisfy both the token's scope and the acting user's own permissions (e.g. emails:send still requires that the user may send from the chosen account).

Conventions

• Format: JSON. Single resources are { "data": { … } }; paginated collections are { "data": [ … ], "meta": { … } }.
• Pagination: ?page= and ?per_page= (default 25, max 100). A few small reference collections (document types, Scout messages) are returned unpaginated and carry no meta.
• Rate limit: 600 requests/minute per client (HTTP 429 when exceeded).
• Errors: { "error": { "code": "…", "message": "…" } }, with validation details under error.details where relevant.
• 404, not 403, is returned for resources you can't see, so the API never reveals the existence of another workspace's data.