Authentication

All API requests require an Authorization header with a Bearer token (API key). Each account can generate multiple named keys, see when they were last used, and revoke them at any time.

Header format

Authorization: Bearer cbct_live_a3f9b1c2d4e5f6g7h8i9j0k1l2m3n4o5

Two key types: live and test

CBCTHub uses the same prefix scheme as Stripe to separate environments. Production keys start with cbct_live_ and operate on real data; sandbox keys start with cbct_test_ and are fully isolated. See the Sandbox / Test mode section for details.

# Producción
Authorization: Bearer cbct_live_a3f9b1c2d4e5f6g7h8i9j0k1l2m3n4o5

# Sandbox
Authorization: Bearer cbct_test_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4

How to create an API key

1. Sign up at cbcthub.com/signup (Free plan available).
2. In the dashboard, open Settings → API.
3. Give it a descriptive name (e.g. “Internal clinic system”) and click Create key.
4. The key is shown ONLY ONCE. Copy it and store it in your secret manager (environment variables, AWS Secrets Manager, Vault, Doppler).

Permissions by scope

Each key has scopes that determine what it can do. Today keys are created with both scopes enabled:

• exams:read — list and read exams
• exams:write — create, confirm, edit and delete exams; share, extras, embed, access-pin, consent and reports
• webhooks:read / webhooks:write — manage webhook subscriptions (list, create, update, delete, test, deliveries).
• referrers:read / referrers:write — CRUD over the referring dentists directory.
• templates:read / templates:write — CRUD over plate templates for radiology reports.
• support:read / support:write — read and create support tickets.
• account:read / account:write — read activity log and notifications; mark notifications as read.

New keys are currently created with ALL scopes enabled. Per-key granularity will arrive in a future release. "read" scopes cover GET/HEAD; "write" scopes cover POST/PATCH/DELETE.

Revoking keys

From Settings → API you can revoke any key. Revocation is immediate: subsequent calls return 401. Revoked keys stay listed for audit purposes but cannot be reactivated.

What happens with an invalid key

If the key is missing, malformed, invalid or revoked, you get a 401 unauthorized:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or revoked API key."
  }
}

API versioning

CBCTHub uses date-based versioning (Stripe-style). Send the X-CBCTHub-Version: 2026-06-23 header on every request to pin the API version your system expects. If you omit it, we use the latest stable version — fine to get started, risky in production if we ship a breaking change.

curl https://cbcthub.com/api/v1/me \
  -H "Authorization: Bearer cbct_live_..." \
  -H "X-CBCTHub-Version: 2026-06-23"

Supported versions today: 2026-06-23 (the only stable one for now). When we ship a new version we keep the previous ones active for at least 12 months so you can migrate at your own pace.

If you send an invalid or unsupported value in the header, we return 400 with code unsupported_api_version and the list of accepted versions.

{
  "error": {
    "code": "unsupported_api_version",
    "message": "Version \"2024-01-01\" is not supported. Supported versions: 2026-06-23. Use the latest: 2026-06-23.",
    "supported": ["2026-06-23"],
    "latest": "2026-06-23"
  }
}

Try it from here

Paste your API key below and make a real call to GET /api/v1/me. It is the fastest way to validate your key works — your key stays only in your browser, it never goes back to CBCTHub outside the request you fire. Create or manage keys from Settings → API.