Authentification et clés API

Comment les requêtes s'authentifient

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." }'

Anatomie d'une clé

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

• Préfixe : bk_{region}_ nomme le type d'identifiant et sa région. Le préfixe fixe et distinctif permet aux scanners de secrets de reconnaître une clé Bird dans le code, et le segment de région dirige votre requête vers le bon hôte.
• Charge utile : 23 caractères aléatoires portant 136 bits d'entropie.
• Somme de contrôle : les 6 derniers caractères sont une somme de contrôle du reste de la clé, de sorte qu'un SDK ou le API peut rejeter immédiatement une clé mal saisie ou tronquée, avant même de la rechercher.

Créer une clé

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

• Les portées sont modifiables. La modification remplace l'ensemble de permissions et conserve le même secret. Vous pouvez accorder les portées détenues par votre propre compte. Si la clé a été créée avant de pouvoir prendre en charge une permission telle que voice, effectuez une rotation pour ajouter cette permission. Les clés révoquées et les clés déjà remplacées par rotation ne peuvent pas être modifiées.
• L'expiration est fixe. Définissez expires_at lorsqu'une clé doit cesser de fonctionner à un moment connu (engagement d'un prestataire, fenêtre de migration). Passé ce moment, la clé renvoie 401 ; une clé sans expiration reste active jusqu'à sa révocation.
• La gestion des clés reste entre les mains des personnes. Créer, modifier et révoquer des clés nécessite la permission api_keys:write, détenue par les rôles administrateur et développeur de l'espace de travail (voir Utilisateurs, équipes et rôles) et jamais accordable à une clé API elle-même. Une clé compromise ne peut pas créer d'autres clés.

Portées et niveaux

Révoquer une clé

Rotation d'une clé

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

1. Créez une nouvelle clé avec les mêmes portées.
2. Déployez la nouvelle clé sur vos services.
3. Surveillez le last_used_on de l'ancienne clé jusqu'à ce que le trafic ait basculé.
4. Révoquez l'ancienne clé.

Les clés appartiennent à l'espace de travail

• Les clés survivent aux départs. Lorsqu'un employé quitte l'entreprise et que son compte utilisateur est supprimé, les clés qu'il a créées continuent de fonctionner. Vous n'avez jamais de panne de production parce que la personne qui a cliqué sur "create" a quitté l'entreprise. (Son départ reste toutefois un bon signal pour effectuer la rotation des clés auxquelles elle avait accès.)
• La portée de la clé s'arrête à l'espace de travail. Elle ne peut jamais effectuer d'opérations au niveau de l'organisation : facturation, membres de l'organisation, paramètres de l'organisation.

Le chemin délégué : jetons OAuth pour le CLI et le serveur MCP

Étapes suivantes

• Référence d'authentification : sémantique des en-têtes de requête et réponses d'erreur
• Régions : hôtes régionaux et routage
• Utilisateurs, équipes et rôles : qui peut gérer les clés
• Espace de travail : l'espace de travail auquel une clé est liée