Autenticação

Toda solicitação à API se autentica com uma chave API passada como bearer token no header Authorization:

curl https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."

As chaves têm escopo de espaço de trabalho: uma chave se autentica como seu espaço de trabalho, carrega os escopos escolhidos na criação e acessa apenas os recursos desse espaço de trabalho. O Guia de autenticação e chaves API explica como criar, definir escopos, rotacionar e revogar chaves: crie-as no dashboard em Platform tools > API keys ou, sem navegador, com bird api-keys create. Esta página cobre o contrato no nível de protocolo.

Formato da chave

Uma chave começa com bk_{region}_, que indica a região onde ela foi criada. Chaves bk_us1_ são válidas apenas para https://us1.platform.bird.com, e chaves bk_eu1_ apenas para https://eu1.platform.bird.com. Os SDKs oficiais e o CLI usam esse prefixo para escolher o host.

A chave completa é retornada uma única vez, na resposta que a cria. O texto original não pode ser recuperado novamente, e o dashboard exibe apenas um key_prefix curto (os 15 primeiros caracteres). Revogue e substitua uma chave perdida.

Respostas de falha

Todas as falhas usam a resposta de erro padrão.

O corpo 421 Misdirected Request (tipo de erro misdirected_error, código E01010) informa o host regional correto, para que o cliente detecte o erro e reenvie sem suposições. Consulte URLs base e regiões.

Sessões do dashboard não são chaves API

O dashboard Bird não usa chaves API: uma pessoa que faz login recebe um cookie de sessão, com escopo das suas próprias permissões de usuário. Cookies de sessão não são aceitos na superfície programática API, e chaves API não são aceitas pelo dashboard. Cargas de trabalho de servidor sempre usam chaves API.

Relacionados

• Guia de autenticação e chaves API: criação, definição de escopos, rotação e revogação de chaves
• URLs base e regiões: hosts regionais e o modelo de regiões
• Erros: a resposta de erro e o catálogo