Un expéditeur planifié doit continuer à fonctionner lorsque l'employé qui l'a configuré quitte l'entreprise. Un outil agissant pour cet employé a besoin d'un accès qui suit ses permissions.
Choisissez l'identifiant en fonction de cette propriété. Ne laissez aucun des deux identifiants dans le code côté navigateur ni dans les journaux, car quiconque le détient peut tenter des requêtes authentifiées.
Que permet chaque identifiant ?
Une clé API agit pour un espace de travail. Un jeton OAuth permet à un outil autorisé d'agir pour une personne.
Les clés Bird API commencent par bk_. Leurs permissions appartiennent à l'espace de travail, donc supprimer le créateur ne les invalide pas. N'accordez que les portées dont le service a besoin pour limiter ce qu'une clé exposée peut faire.
Une clé ne peut pas effectuer d'opérations au niveau de l'organisation, comme gérer les membres de l'organisation ou la facturation. Ajouter davantage de portées d'espace de travail ne supprime pas cette limite.
Lorsque vous vous connectez via le serveur CLI ou MCP, vous autorisez un outil avec un sous-ensemble de vos permissions. L'outil reçoit un jeton bt_ de courte durée. Il gère le renouvellement du jeton ; ne copiez donc pas ce jeton dans le gestionnaire de secrets d'un service.
Révoquez un outil autorisé via Profile > Connected apps. Utilisez la page authentication pour choisir les portées et distinguer les clés d'espace de travail des autorisations personnelles.
Comment effectuer la rotation d'une clé API ?
Émettez un remplacement et déployez-le avant la fin du chevauchement de l'ancienne clé.
Vous pouvez effectuer la rotation depuis le tableau de bord, avec bird api-keys rotate, ou via l'outil api_keys_rotate MCP. La rotation CLI et MCP nécessite une autorisation personnelle avec api_keys:write. Une clé API ne peut pas détenir cette permission ni effectuer la rotation d'une autre clé.
La rotation renvoie le token du remplacement une seule fois. Enregistrez-le immédiatement, car les lectures ultérieures ne permettent pas de le récupérer. Le remplacement conserve l'ancien nom et les restrictions d'IP. Il conserve aussi les permissions, sauf si vous fournissez de nouvelles scopes.
Définissez grace_period pour contrôler le chevauchement. Sa valeur par défaut est 24h ; terminez donc le déploiement dans cette journée. Une expiration antérieure sur l'ancienne clé reste en vigueur. La rotation ne la prolonge jamais.
Utilisez grace_period: "0" lorsqu'une clé divulguée doit être révoquée immédiatement. La validation en cache peut encore l'accepter brièvement, comme décrit ci-dessous.
- Demandez la rotation et enregistrez le jeton renvoyé.
- Déployez le remplacement sur chaque service avant la fin du chevauchement.
- Confirmez les requêtes réussies avec le remplacement dans les journaux du service.
- Laissez l'ancienne clé expirer, ou révoquez-la lorsque la bascule est terminée.
La référence de rotation couvre la commande et ses options.
Que peut-il mal se passer pendant la rotation ?
Une réponse perdue peut vous laisser avec un remplacement émis dont vous n'avez jamais enregistré le jeton.
Utilisez la même Idempotency-Key lorsque vous réessayez la requête de rotation, afin que Bird puisse rejouer sa réponse. Une clé ne peut être rotée qu'une seule fois. Sans la même clé d'idempotence, répéter la rotation renvoie 409. Effectuez la rotation du remplacement pour un changement planifié ultérieur.
Une clé révoquée ne peut pas être rotée. Créez une nouvelle clé si l'originale est déjà révoquée.
Le remplacement n'a pas d'expiration, même si l'original en avait une. Vous ne pouvez pas ajouter d'expiration après coup. Créez une nouvelle clé avec expires_at lorsqu'elle doit cesser de fonctionner à un moment connu.
Pour un déploiement de durée incertaine, créez une seconde clé et gérez le chevauchement vous-même. Déployez-la avant de révoquer l'originale. La période de grâce d'une rotation ne peut pas être prolongée après la requête.
À quelle vitesse la révocation prend-elle effet ?
Une clé révoquée peut rester acceptée pendant cinq secondes au maximum, le temps que la validation en cache expire.
Considérez une clé exposée comme utilisable pendant toute cette fenêtre. La révocation est permanente : une clé révoquée ne peut pas être réactivée. Bird conserve son enregistrement à des fins d'audit.
Utilisez key_prefix ou fingerprint pour identifier une clé dans les échanges avec le support. N'incluez jamais l'identifiant complet, car ces identifiants suffisent à la distinguer sans accorder d'accès.
Quel identifiant choisir ?
Choisissez en fonction de qui possède la charge de travail et des permissions nécessaires.
- Clé API : un service qui doit continuer à fonctionner indépendamment de son créateur.
- Autorisation OAuth : un CLI ou agent agissant dans les limites des permissions d'une personne.
- Rotation : une clé de remplacement que vous pouvez déployer pendant un chevauchement connu.
- Nouvelle clé avec expiration : un identifiant qui doit cesser de fonctionner à un moment précis.
En bref
Les identifiants de service appartiennent à l'espace de travail.
Une clé survit au départ de son créateur. Un outil utilisant OAuth agit dans les limites des permissions de la personne qui l'a autorisé.
Déployez pendant le chevauchement de rotation.
L'ancienne clé continue de fonctionner pendant 24 heures par défaut, sauf si son expiration existante intervient plus tôt.
Enregistrez le remplacement dès son émission.
La rotation renvoie le nouveau jeton une seule fois. Conservez la même clé d'idempotence si vous réessayez la requête de rotation.
La révocation a une courte fenêtre de propagation.
La validation en cache peut accepter une clé révoquée pendant cinq secondes au maximum ; tenez compte de ce délai après une fuite.