Autenticação

Toda chamada usa Bearer token com a sua API key (prefixo bk_):

Authorization: Bearer bk_sua_chave_aqui

Gere e revogue chaves no painel (Configurações → API keys). A chave em claro aparece uma única vez na criação; depois só o preview mascarado (bk_AbC…wXyZ). Revogar preserva a evidência (a chave fica inativa, não some).

Escopos

Cada chave tem um escopo:

Uma chave read chamando uma rota de escrita recebe 403 insufficient_scope. Use chaves read em integrações que só observam, e write só onde precisa agir (princípio do menor privilégio).

Erros de autenticação

• 401 {"error":"não autorizado"}: sem header, chave inválida ou revogada, ou tenant suspenso.
• 403 {"error":"insufficient_scope"}: chave read numa rota de escrita.
• 403 {"error":"account_locked"}: a sua conta ribbo está em modo só leitura. Consultas seguem liberadas, e também corrigir dados de cliente, estornar e cancelar.

Segurança

• A chave identifica o seu tenant. Dados de outro tenant retornam 404 (indistinguível de "não existe"): nunca há vazamento cross-tenant.
• Guarde a chave como segredo (variável de ambiente ou cofre). Nunca a exponha no front-end.