Authentification

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

Exemple de code

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é

Exemple de code

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.

Statut	Quand
401	L'en-tête Authorization est absent, la clé est mal formée ou inconnue, ou la clé a été révoquée.
403	La clé est valide mais ne possède pas la portée requise par le point de terminaison.
421	La région de la clé ne correspond pas à l'hôte, par exemple une clé bk_eu1_... envoyée à us1.platform.bird.com.

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

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Comprendre le conceptShould I use a Bird SDK or call the API directly?Suivre le parcours d'apprentissageBuild your first integration Guide d'implémentationSend your first email

Obtenir un guide d'implémentation