Authentification

Chaque requête API s'authentifie avec une clé API transmise comme jeton bearer dans l'en-tête Authorization :

curl https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."

Les clés sont liées à un espace de travail : une clé s'authentifie en tant que votre espace de travail, porte les portées choisies à la création et ne peut accéder qu'à ses ressources. La création, la portée, la rotation et la révocation des clés sont décrites dans le guide Authentification et clés API : créez-les dans le tableau de bord sous Developers > Clés API, ou sans navigateur avec bird api-keys create. Cette page couvre le contrat au niveau du protocole.

Format de clé

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

Une clé est bk_{region}_{payload}{checksum} :

• bk_{region}_ : Le préfixe identifie le type d'identifiant et la région où la clé a été créée. Les clés bk_us1_ ne sont valides que pour https://us1.platform.bird.com, et les clés bk_eu1_ uniquement pour https://eu1.platform.bird.com. Les SDK officiels et le CLI utilisent ce préfixe pour choisir l'hôte. Le préfixe fixe bk_ est enregistré auprès de GitHub secret scanning : une clé Bird divulguée dans un dépôt public est détectée et signalée.
• Payload : Une longue chaîne aléatoire avec 128+ bits d'entropie.
• Checksum : Les 6 derniers caractères sont une somme de contrôle du reste de la clé, permettant au client de rejeter localement une clé mal saisie ou tronquée avant toute requête.

La clé complète n'est renvoyée qu'une seule fois, dans la réponse qui la crée. Le texte en clair ne peut plus être récupéré, et le tableau de bord n'affiche qu'un court key_prefix (les 12 premiers caractères). Révoquez et remplacez une clé perdue.

Réponses d'échec

Tous les échecs utilisent la réponse d'erreur standard.

Le corps 421 Misdirected Request (type d'erreur misdirected_error, code E01010) nomme l'hôte régional correct, permettant au client de détecter l'erreur et de renvoyer la requête sans avoir à deviner. Voir URL de base et régions.

Les sessions du tableau de bord ne sont pas des clés API

Le tableau de bord Bird n'utilise pas de clés API : une personne qui se connecte obtient un cookie de session, limité à ses propres permissions utilisateur. Les cookies de session ne sont pas acceptés sur la surface programmatique API, et les clés API ne sont pas acceptées par le tableau de bord. Les charges de travail serveur utilisent toujours des clés API.

Ressources associées

• Guide Authentification et clés API : création, portée, rotation et révocation des clés
• URL de base et régions : hôtes régionaux et modèle de régions
• Erreurs : la réponse d'erreur et le catalogue