Autenticação

Todas as requests à API exigem um header Authorization com um Bearer token (API key). Cada conta pode gerar múltiplas keys nomeadas, ver o último uso e revogá-las a qualquer momento.

Formato do header

Authorization: Bearer cbct_live_a3f9b1c2d4e5f6g7h8i9j0k1l2m3n4o5

Dois tipos de keys: live e test

O CBCTHub usa o mesmo esquema de prefixos que o Stripe para separar ambientes. As keys de produção começam com cbct_live_ e operam sobre dados reais; as keys de sandbox começam com cbct_test_ e estão totalmente isoladas. Veja a seção Sandbox / Test mode para os detalhes.

# Producción
Authorization: Bearer cbct_live_a3f9b1c2d4e5f6g7h8i9j0k1l2m3n4o5

# Sandbox
Authorization: Bearer cbct_test_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4

Como criar uma API key

1. Crie uma conta em cbcthub.com/signup (plano Free disponível).
2. No dashboard, abra Ajustes → API.
3. Dê um nome descritivo (ex.: “Sistema clínico interno”) e clique em Criar key.
4. A key é mostrada UMA ÚNICA VEZ. Copie e guarde no seu secret manager (variáveis de ambiente, AWS Secrets Manager, Vault, Doppler).

Permissões por scope

Cada key tem scopes que determinam o que ela pode fazer. Hoje as keys são criadas com ambos os scopes ativados:

• exams:read — listar e ler exames
• exams:write — criar, confirmar, editar e excluir exames; share, extras, embed, access-pin, consent e reports
• webhooks:read / webhooks:write — gerenciar subscriptions de webhooks (listar, criar, atualizar, excluir, test, deliveries).
• referrers:read / referrers:write — CRUD do diretório de dentistas solicitantes.
• templates:read / templates:write — CRUD de modelos de placas para laudos radiológicos.
• support:read / support:write — ler e criar tickets de suporte.
• account:read / account:write — ler activity log e notificações; marcar notificações como lidas.

Hoje as keys novas são criadas com TODOS os scopes ativos. A granularidade por-key chegará em versões futuras. Os scopes "read" cobrem GET/HEAD; os "write" cobrem POST/PATCH/DELETE.

Revogar keys

Em Ajustes → API você pode revogar qualquer key. A revogação é imediata: chamadas posteriores retornam 401. As keys revogadas continuam no histórico para auditoria, mas não podem ser reativadas.

O que acontece se a key for inválida

Se a key estiver ausente, malformada, inválida ou revogada, você recebe 401 unauthorized:

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

Versionamento da API

O CBCTHub usa versionamento por data (estilo Stripe). Envie o header X-CBCTHub-Version: 2026-06-23 em cada request para fixar a versão da API que seu sistema espera. Se omitir, usamos a última versão estável — tranquilo para começar, arriscado em produção se publicarmos uma quebra.

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

Versões suportadas hoje: 2026-06-23 (a única estável por ora). Quando publicarmos uma nova, mantemos as anteriores ativas por pelo menos 12 meses para você migrar com calma.

Se enviar um valor inválido ou não suportado no header, retornamos 400 com code unsupported_api_version e a lista de versões aceitas.

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

Teste a partir daqui

Cole sua API key abaixo e faça uma chamada real a GET /api/v1/me. É a forma mais rápida de validar que sua key funciona — sua key fica só no seu navegador, nunca chega ao CBCTHub fora da própria request. Gere ou gerencie keys em Ajustes → API.