Autenticação

A API Pública V1 usa uma API Key por clínica, no esquema HTTP Bearer. Cada chave pertence a uma única clínica e nunca pode selecionar, trocar ou consultar outra.

Onde a chave é aceita

Somente no cabeçalho Authorization, com o prefixo Bearer :

Authorization: Bearer ck_live_EXEMPLO_REDACTED_EXEMPLO_REDACTED_EXEMPLO_REDACTED

A chave nunca deve ser enviada para:

navegador, aplicativo móvel distribuído ou página web;
query string, path, body ou header customizado;
logs, analytics, ferramenta de rastreamento, screenshot ou repositório;
localStorage, sessionStorage, cookies ou cache compartilhado.

A integração é exclusivamente server-to-server, a partir de um backend controlado pela clínica.

Formato da chave

O valor segue o regex ^ck_live_[0-9a-f]{32}_[A-Za-z0-9_-]{43}$:

prefixo fixo ck_live_;
32 caracteres hexadecimais que identificam a credencial;
sufixo de 43 caracteres em base64url gerado a partir de 32 bytes aleatórios (crypto.getRandomValues).

O banco armazena somente o SHA-256 da chave, o prefixo de exibição (24 caracteres), os scopes, as datas de criação/expiração/revogação e o último uso. A chave completa aparece uma única vez, na resposta de criação ou rotação.

Criar uma chave

A criação é feita pelo painel da clínica em Configurações → API. Somente o perfil clinica com status ativo pode administrar chaves; o perfil admin da plataforma e o perfil usuario não recebem impersonação na V1.

Limites por clínica:

no máximo 5 chaves ativas simultâneas;
validade padrão de 90 dias, mínimo 1 e máximo 365;
cada chave precisa de pelo menos 1 scope, no máximo 24;
contacts:delete e followups:execute são de alto risco, ficam fora dos presets e exigem confirmação extra na interface.

Quando a criação é concluída, o painel mostra a chave completa uma única vez. O botão Fechar só habilita após marcar a confirmação de que a chave foi salva em local seguro (secret manager, cofre, variável de ambiente protegida).

Rotacionar e revogar

Rotacionar no painel:

gera uma nova chave com os mesmos scopes e a validade escolhida;
revoga a anterior na mesma transação;
exibe a nova chave uma única vez;
a partir desse instante, a chave antiga retorna 401 invalid_api_key.

Rotação é imediata e deve ser usada em incidente. Para troca sem interrupção de serviço:

crie uma segunda chave ativa;
atualize a integração e valide;
só então revogue a antiga.

Revogar marca revoked_at = now() imediatamente. A auditoria da chave permanece; apenas o uso cessa.

Guardar a chave

Recomendado:

variável de ambiente protegida no servidor da clínica (nunca no repositório);
secret manager (Doppler, AWS Secrets Manager, Google Secret Manager, Azure Key Vault, 1Password, Bitwarden);
arquivo .env ignorado pelo git com permissão 0600.

Perder a chave

Se o painel foi fechado sem copiar, não há recuperação: o banco só guarda o hash. Recupere revogando a metadata criada e gerando outra.

Se houve suspeita de vazamento, revogue imediatamente pelo painel e crie uma nova.