Autenticação

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

Exemplo de código

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 dele. Como criar, definir escopos, rotacionar e revogar chaves está no Guia de autenticação e chaves API: crie-as no dashboard em Developers > Chaves API, ou sem navegador com bird api-keys create. Esta página cobre o contrato no nível de protocolo.

Formato da chave

Exemplo de código

bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ...
└┬┘└┬┘ └──────────┬──────────┘└┬┘
 │  │          payload      checksum
 │  └ region (routes the request)
 └ Bird key prefix

Uma chave é bk_{region}_{payload}{checksum}:

bk_{region}_: O prefixo identifica o tipo de credencial e a região onde a chave 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. O prefixo fixo bk_ é registrado no GitHub secret scanning, então uma chave Bird vazada em um repositório público é detectada e reportada.
Payload: Uma string aleatória longa com mais de 128 bits de entropia.
Checksum: Os 6 últimos caracteres são um checksum do restante da chave, permitindo que o cliente rejeite uma chave digitada incorretamente ou truncada localmente, antes de qualquer solicitação.

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 12 primeiros caracteres). Revogue e substitua uma chave perdida.

Respostas de falha

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

Status	Quando
401	O header Authorization está ausente, a chave é malformada ou desconhecida, ou a chave foi revogada.
403	A chave é válida, mas não possui o escopo que o endpoint exige.
421	A região da chave não corresponde ao host, como uma chave bk_eu1_... enviada para us1.platform.bird.com.

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

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Entenda o conceitoShould I use a Bird SDK or call the API directly?Siga o percurso de aprendizagemBuild your first integration Guia de implementaçãoSend your first email

Obtenha um resumo de implementação