Autenticazione e chiavi API

Come si autenticano le richieste

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 di una chiave

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

• Prefisso: bk_{region}_ indica il tipo di credenziale e la sua regione. Il prefisso fisso e distintivo è ciò che permette ai secret scanner di riconoscere una chiave Bird nel codice, e il segmento di regione instrada la richiesta all'host corretto.
• Payload: 23 caratteri casuali con 136 bit di entropia.
• Checksum: gli ultimi 6 caratteri sono un checksum del resto della chiave, così un SDK o la API possono rifiutare immediatamente una chiave digitata male o troncata, prima ancora di cercarla.

Creare una chiave

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

• Gli scope sono modificabili. La modifica sostituisce l'insieme dei permessi mantenendo lo stesso segreto. Puoi concedere scope di cui dispone il tuo account. Se la chiave è stata creata prima che potesse supportare un permesso come voice, ruotala per aggiungerlo. Le chiavi revocate e quelle già sostituite da una rotazione non possono essere modificate.
• La scadenza è fissa. Imposta expires_at quando una chiave deve smettere di funzionare a un momento noto (l'incarico di un collaboratore, una finestra di migrazione). Superato quel momento la chiave restituisce 401; una chiave senza scadenza resta attiva fino alla revoca.
• La gestione delle chiavi resta alle persone. Creare, modificare e revocare chiavi richiede il permesso api_keys:write, assegnato ai ruoli admin e developer dello spazio di lavoro (vedi Utenti, team e ruoli) e mai concedibile a una chiave API stessa. Una chiave compromessa non può generarne altre.

Scope e livelli

Revocare una chiave

Ruotare una chiave

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

1. Crea una nuova chiave con gli stessi scope.
2. Distribuisci la nuova chiave ai tuoi servizi.
3. Monitora il last_used_on della vecchia chiave finché il traffico non si è spostato.
4. Revoca la vecchia chiave.

Le chiavi appartengono allo spazio di lavoro

• Le chiavi sopravvivono alle partenze. Quando un dipendente lascia l'azienda e il suo account utente viene rimosso, le chiavi che ha creato continuano a funzionare. Non avrai mai un'interruzione in produzione perché la persona che ha cliccato "create" ha lasciato l'azienda. (La sua partenza è comunque un buon motivo per ruotare le chiavi a cui aveva accesso.)
• Il raggio d'azione della chiave si ferma allo spazio di lavoro. Non può mai eseguire operazioni a livello di organizzazione: fatturazione, membri dell'organizzazione, impostazioni dell'organizzazione.

Il percorso delegato: token OAuth per la CLI e il server MCP

Passaggi successivi

• Riferimento all'autenticazione: semantica degli header di richiesta e risposte di errore
• Regioni: host regionali e instradamento
• Utenti, team e ruoli: chi può gestire le chiavi
• Spazio di lavoro: lo spazio di lavoro a cui è legata una chiave