Um remetente agendado deve continuar funcionando quando o funcionário que o configurou sai da empresa. Uma ferramenta que age por esse funcionário precisa de acesso que acompanhe as permissões dele.
Escolha a credencial com base nessa propriedade. Mantenha qualquer uma das credenciais fora de código no navegador e de logs, porque qualquer pessoa que a possuir pode fazer solicitações autenticadas.
O que cada credencial me permite fazer?
Uma chave API age em nome de um espaço de trabalho. Um token OAuth permite que uma ferramenta autorizada aja em nome de uma pessoa.
Chaves Bird API começam com bk_. Suas permissões pertencem ao espaço de trabalho, então remover o criador não as invalida. Conceda apenas os escopos que o serviço precisa para limitar o que uma chave exposta pode fazer.
Uma chave não pode realizar operações no nível da organização, como gerenciar membros da organização ou faturamento. Adicionar mais escopos de espaço de trabalho não remove essa restrição.
Quando você faz login pelo servidor CLI ou MCP, você autoriza uma ferramenta com um subconjunto das suas permissões. A ferramenta recebe um token bt_ de curta duração. Ela gerencia a renovação do token, então não copie esse token para o gerenciador de segredos de um serviço.
Revogue uma ferramenta autorizada em Profile > Connected apps. Use autenticação para escolher escopos e distinguir chaves de espaço de trabalho de concessões pessoais.
Como faço a rotação de uma chave API?
Emita uma substituição e implante-a antes que a sobreposição da chave antiga termine.
Você pode fazer a rotação pelo dashboard, com bird api-keys rotate, ou pela ferramenta api_keys_rotate MCP. A rotação por CLI e MCP exige uma concessão pessoal com api_keys:write. Uma chave API não pode ter essa permissão nem fazer a rotação de outra chave.
A rotação retorna o token da substituição apenas uma vez. Armazene-o imediatamente, porque leituras posteriores não conseguem recuperá-lo. A substituição mantém o nome antigo e as restrições de IP. Ela também mantém as permissões, a menos que você forneça novos scopes.
Defina grace_period para controlar a sobreposição. O padrão é 24h, então conclua a implantação dentro desse dia. Uma expiração anterior na chave antiga ainda se aplica. A rotação nunca a estende.
Use grace_period: "0" quando uma chave vazada precisar ser revogada imediatamente. A validação em cache ainda pode aceitá-la brevemente, conforme descrito abaixo.
- Solicite a rotação e salve o token retornado.
- Implante a substituição em cada serviço antes que a sobreposição termine.
- Confirme solicitações bem-sucedidas com a substituição por meio dos logs do serviço.
- Deixe a chave antiga expirar ou revogue-a quando a transição estiver completa.
A referência de rotação cobre o comando e suas opções.
O que pode dar errado durante a rotação?
Uma resposta perdida pode deixar você com uma substituição emitida cujo token você nunca salvou.
Use o mesmo Idempotency-Key ao tentar novamente a solicitação de rotação para que Bird possa reproduzir sua resposta. Uma chave só pode ser rotacionada uma vez. Sem a mesma chave de idempotência, repetir a rotação retorna 409. Faça a rotação da substituição para uma mudança planejada posterior.
Uma chave revogada não pode ser rotacionada. Crie uma nova chave se a original já tiver sido revogada.
A substituição não tem expiração, mesmo quando a original tinha. Você não pode adicionar uma expiração depois. Crie uma nova chave com expires_at quando ela precisar parar de funcionar em um horário conhecido.
Para uma implantação com duração incerta, crie uma segunda chave e gerencie a sobreposição você mesmo. Implante-a antes de revogar a original. O período de tolerância de uma rotação não pode ser estendido após a solicitação.
Em quanto tempo a revogação entra em vigor?
Uma chave revogada pode continuar sendo aceita por até cinco segundos enquanto a validação em cache expira.
Trate uma chave exposta como utilizável durante toda essa janela. A revogação é permanente, então uma chave revogada não pode ser reativada. Bird mantém o registro para auditoria.
Use key_prefix ou fingerprint para identificar uma chave em conversas com o suporte. Nunca inclua a credencial completa, porque esses identificadores são suficientes para distingui-la sem conceder acesso.
Qual credencial devo escolher?
Escolha de acordo com quem é responsável pela carga de trabalho e quais permissões ela precisa.
- Chave API: um serviço que deve continuar funcionando independentemente de quem o criou.
- Concessão OAuth: um CLI ou agente agindo dentro das permissões de uma pessoa.
- Rotação: uma chave substituta que você pode implantar durante uma sobreposição conhecida.
- Nova chave com expiração: uma credencial que deve parar de funcionar em um momento específico.
Em resumo
Credenciais de serviço pertencem ao espaço de trabalho.
Uma chave sobrevive à saída de quem a criou. Uma ferramenta usando OAuth age dentro das permissões da pessoa que a autorizou.
Implante durante a sobreposição da rotação.
A chave antiga continua funcionando por 24 horas por padrão, a menos que sua expiração existente chegue antes.
Salve a substituição quando ela for emitida.
A rotação retorna o novo token apenas uma vez. Use a mesma chave de idempotência se você tentar novamente a solicitação de rotação.
A revogação tem uma curta janela de propagação.
A validação em cache pode aceitar uma chave revogada por até cinco segundos, então leve em conta esse atraso após um vazamento.