Skip to main content

​
Formato da chave

Toda chamada à API pública é autenticada com uma chave de API no cabeçalho Authorization, usando o esquema Bearer:
A chave tem duas partes separadas por um ponto: um identificador de prefixo (bd_live_<id>) e um segredo (<secret>). Ambas juntas formam a credencial completa.
A chave é exibida uma única vez, no momento da criação, em Minha Clínica → API e Webhooks. O ByDoctor armazena apenas o hash — não é possível recuperar uma chave perdida. Se isso acontecer, revogue a chave antiga e crie uma nova.

​
Escopos

Na criação, em Minha Clínica → API e Webhooks, você escolhe o acesso da chave: Somente leitura (appointments:read + patients:read) ou Acesso total (os quatro escopos). Uma rota exige exatamente um escopo; uma chave sem ele recebe 403 Forbidden. Por padrão uma chave nasce somente leitura; a escrita é concedida por chave, de forma explícita. Os escopos de uma chave não podem ser alterados depois — crie uma chave nova e revogue a antiga. Uma chave sem o escopo recebe 403 com a mensagem This API key does not have the "patients:write" scope., nomeando o escopo que falta. Chave ausente, mal formatada, inválida, revogada ou expirada recebe 401 com o motivo; veja Erros. Chaves criadas antes da escrita existir continuam somente leitura, e chaves criadas antes dos pacientes existirem não recebem os escopos de pacientes: o acesso ao cadastro de pacientes nunca é concedido a uma chave existente sem que a clínica crie uma nova.

​
Revogação e expiração

Revogar uma chave em Minha Clínica → API e Webhooks tem efeito imediato: a próxima requisição com essa chave recebe 401 Unauthorized. Não há período de carência. Uma chave também pode ter uma data de expiração (expires_at), definida na criação. Uma vez expirada, ela passa a se comportar como uma chave revogada: toda requisição recebe 401 Unauthorized.

​
Limites de uso (rate limits)

Cada chave está sujeita a dois limites, aplicados de forma independente: Ao exceder um dos limites, a API responde 429 Too Many Requests com um cabeçalho Retry-After indicando em quantos segundos tentar novamente. Implemente backoff e nova tentativa; não faça polling agressivo — para manter uma cópia local em dia, prefira a receita de sincronização combinada com webhooks.

​
Segurança

Uma chave de API concede acesso a dados de pacientes e de agendamentos, que são dados de saúde. Trate-a como qualquer outro segredo de produção:
  • Armazene em um cofre de segredos (secrets manager), nunca em código-fonte versionado.
  • Nunca exponha a chave em código do lado do cliente (browser, app mobile) — toda chamada deve partir de um backend seu.
  • Nunca faça commit da chave em um repositório git, mesmo privado.
  • Revogue e recrie a chave se suspeitar de exposição.