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 lors de sa création et ne peut accéder qu'aux ressources de cet espace. 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 Platform tools > API keys, ou sans navigateur avec bird api-keys create. Cette page décrit le contrat au niveau du protocole.
Format de clé
Une clé commence par bk_{region}_, qui indique la région où elle 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.
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 15 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.