Authentication

ChatBlocks supports two authentication methods for the main API surface. Both work with page and page-job endpoints.

API Keys (recommended for programmatic access)

API keys are bearer tokens prefixed with cb_live_. Pass them in the Authorization header:


curl -X GET https://chatblocks.app/api/pages \
  -H "Authorization: Bearer cb_live_YOUR_KEY"

Managing keys

Create: Go to Settings or POST /api/keys (session auth required)
List: GET /api/keys (session auth required)
Revoke: DELETE /api/keys/:id (session auth required)

Key properties

Property	Description
Prefix	`cb_live_`
Storage	SHA-256 hash stored in database
Display	Full key shown once on creation, only prefix shown after
Revocation	Soft-delete via `revoked_at` timestamp

Note: API key management endpoints (/api/keys) require browser session auth, not API key auth.

Agent Connect Tokens

Agent connect tokens are not API credentials. They are short-lived shared secrets that let a signed-in user attach an agent instance to their account through the web UI.

Use this flow when your agent needs an account-linking handshake:

Generate a token in Settings
Paste that token into your agent
Open the connect link while signed in
Poll POST /api/agent/token until the token is claimed

See the full Agent Connect guide for the exact flow and example requests.

Browser Session (web)

When using ChatBlocks through the web dashboard, authentication is handled automatically via browser session cookies. The same session works for API calls made from the browser.

This is used internally by the dashboard and is the only method accepted for key management endpoints.

Public endpoints

These endpoints require no authentication:

Endpoint	Description
`GET /api/qr/:username/:slug`	Generate QR code PNG
`GET /api/schema`	Get page spec JSON Schema
`GET /:username/:slug`	View a published page
`GET /:username`	View a user’s default page