Autenticação e chaves API

Como as solicitações se autenticam

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

await bird.email.send({
  from: "hello@yourdomain.com",
  to: ["delivered@messagebird.dev"],
  subject: "Hi",
  text: "Hello.",
});

import os

from bird import Bird

client = Bird(api_key=os.environ["BIRD_API_KEY"])

client.email.send(
    from_="hello@yourdomain.com",
    to=["delivered@messagebird.dev"],
    subject="Hi",
    text="Hello.",
)

client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
	log.Fatal(err)
}

_, err = client.Email.Send(context.Background(), bird.EmailSendParams{
	From:    "hello@yourdomain.com",
	To:      []string{"delivered@messagebird.dev"},
	Subject: "Hi",
	Text:    "Hello.",
})

use MessageBird\Bird;

$bird = new Bird(getenv('BIRD_API_KEY') ?: '');

$bird->email->send(
    from: 'hello@yourdomain.com',
    to: ['delivered@messagebird.dev'],
    subject: 'Hi',
    text: 'Hello.',
);

export BIRD_API_KEY="bk_us1_..."

bird email send \
  --from hello@yourdomain.com \
  --to delivered@messagebird.dev \
  --subject Hi \
  --text Hello.

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "hello@yourdomain.com", "to": ["delivered@messagebird.dev"], "subject": "Hi", "text": "Hello." }'

Anatomia de uma chave

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

• Prefixo: bk_{region}_ identifica o tipo de credencial e sua região. O prefixo fixo e distintivo é o que permite que scanners de segredos reconheçam uma chave Bird no código, e o segmento de região direciona sua solicitação ao host correto.
• Payload: 23 caracteres aleatórios com 136 bits de entropia.
• Checksum: os últimos 6 caracteres são um checksum do restante da chave, para que um SDK ou o API possa rejeitar imediatamente uma chave digitada incorretamente ou truncada, antes mesmo de ser consultada.

Criando uma chave

bird auth login --scope api_keys:write
bird api-keys create --body-file - <<'JSON'
{
  "name": "Email operations production key",
  "scopes": [{ "scope": "emails", "level": "write" }]
}
JSON

• Escopos são editáveis. A edição substitui o conjunto de permissões e mantém o mesmo segredo. Você pode conceder escopos que sua própria conta possui. Se a chave foi criada antes de poder suportar uma permissão como voice, faça a rotação para adicionar essa permissão. Chaves revogadas e chaves já substituídas por rotação não podem ser editadas.
• A expiração é fixa. Defina expires_at quando uma chave deve parar de funcionar em um momento conhecido (contrato de um prestador, janela de migração). Após esse momento, a chave retorna 401; uma chave sem expiração permanece ativa até ser revogada.
• O gerenciamento de chaves fica com pessoas. Criar, editar e revogar chaves exige a permissão api_keys:write, mantida pelos papéis de admin e developer do espaço de trabalho (veja Usuários, equipes e papéis) e nunca concedível a uma chave API em si. Uma chave vazada não pode gerar mais chaves.

Escopos e níveis

Revogando uma chave

Rotacionando uma chave

bird auth login --scope api_keys:write
bird api-keys rotate key_01hqz8kp3v9x2m --yes

1. Crie uma nova chave com os mesmos escopos.
2. Implante a nova chave nos seus serviços.
3. Monitore o last_used_on da chave antiga até que o tráfego tenha migrado.
4. Revogue a chave antiga.

As chaves pertencem ao espaço de trabalho

• As chaves sobrevivem a saídas. Quando um funcionário sai e sua conta de usuário é removida, as chaves que ele criou continuam funcionando. Você nunca tem uma interrupção em produção porque a pessoa que clicou em "create" saiu da empresa. (A saída dela ainda é um bom motivo para rotacionar chaves às quais ela tinha acesso.)
• O alcance da chave para no espaço de trabalho. Ela nunca pode executar operações em nível de organização: cobrança, membros da organização, configurações da organização.

O caminho delegado: tokens OAuth para o CLI e o MCP server

Próximos passos

• Referência de autenticação: semântica do cabeçalho da solicitação e respostas de erro
• Regiões: hosts regionais e roteamento
• Usuários, equipes e papéis: quem pode gerenciar chaves
• Espaço de trabalho: o espaço de trabalho ao qual uma chave se vincula