Autenticación

Todas las requests a la API requieren un header Authorization con un Bearer token (API key). Cada cuenta puede generar múltiples keys con nombre, ver el último uso y revocarlas en cualquier momento.

Formato del header

Authorization: Bearer cbct_live_a3f9b1c2d4e5f6g7h8i9j0k1l2m3n4o5

Dos tipos de keys: live y test

CBCTHub usa el mismo esquema de prefixes que Stripe para distinguir entornos. Las keys de producción empiezan con cbct_live_ y operan sobre datos reales; las keys de sandbox empiezan con cbct_test_ y están totalmente aisladas. Mira la sección Sandbox / Test mode para el detalle.

# Producción
Authorization: Bearer cbct_live_a3f9b1c2d4e5f6g7h8i9j0k1l2m3n4o5

# Sandbox
Authorization: Bearer cbct_test_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4

Cómo crear una API key

1. Crea una cuenta en cbcthub.com/signup (Free disponible).
2. En el dashboard, abre Ajustes → API.
3. Pon un nombre descriptivo (ej: “Sistema clínico interno”) y haz clic en Crear key.
4. La key se muestra UNA SOLA VEZ. Cópiala y guárdala en el secret manager de tu sistema (variables de entorno, AWS Secrets Manager, Vault, Doppler).

Permisos por scope

Cada key tiene scopes que indican qué puede hacer. Hoy las keys se crean con ambos scopes activos:

• exams:read — listar y leer exámenes
• exams:write — crear, confirmar, editar y eliminar exámenes; compartir, extras, embed, access-pin, consent y reports
• webhooks:read / webhooks:write — gestionar subscriptions de webhooks (listar, crear, actualizar, eliminar, test, deliveries).
• referrers:read / referrers:write — CRUD del directorio de dentistas derivadores.
• templates:read / templates:write — CRUD de plantillas de placas para informes radiológicos.
• support:read / support:write — leer y crear tickets de soporte.
• account:read / account:write — leer activity log y notificaciones; marcar notificaciones como leídas.

Hoy las keys nuevas se crean con TODOS los scopes activos. La granularidad por-key llegará en versiones futuras. Los scopes "read" cubren GET/HEAD; los "write" cubren POST/PATCH/DELETE.

Revocar keys

Desde Ajustes → API puedes revocar cualquier key. La revocación es inmediata: las llamadas posteriores devuelven 401. Las keys revocadas quedan en el listado por audit, pero no se reactivan.

Qué pasa si la key es inválida

Si la key es inválida, ausente, malformada o revocada, recibes 401 unauthorized:

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

Versionado de la API

CBCTHub usa versionado fecha-basado (estilo Stripe). Envía el header X-CBCTHub-Version: 2026-06-23 en cada request para fijar la versión de la API que tu sistema espera. Si lo omites, usamos la última versión estable — fácil para empezar, riesgoso para producción si publicamos un cambio incompatible.

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

Versiones soportadas hoy: 2026-06-23 (la única estable por ahora). Cuando publiquemos una nueva, mantenemos las anteriores activas al menos 12 meses para que migres con calma.

Si envías un valor inválido o no soportado en el header, devolvemos 400 con code unsupported_api_version y la lista de versiones aceptadas.

{
  "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"
  }
}

Pruébala desde aquí

Pega tu API key abajo y haz una llamada real a GET /api/v1/me. Es la forma más rápida de validar que tu key funciona — tu key queda solo en tu navegador, nunca llega a CBCTHub fuera de la propia request. Genera o gestiona keys en Ajustes → API.