Créer une clé d'API et brancher votre suite de tests

Une clé d'API permet à vos tests d'appeler l'API sans navigateur et sans session. Elle appartient à l'organisation, ce qui veut dire qu'elle survit au départ de la personne qui l'a créée : votre intégration continue ne casse pas parce que quelqu'un change d'entreprise.

Il faut être propriétaire ou administrateur de l'organisation pour en créer une.

Créer une clé

Ouvrez Paramètres → Clés d'API → Créer une clé et remplissez quatre champs.

1. Un nom. C'est ce qui vous permettra de savoir laquelle révoquer dans six mois : « CI GitHub », « recette Camille ».
2. Ce qu'elle peut faire. Dans les espaces : lire, ou lire et écrire. Sur l'organisation : rien, lire, ou lire et écrire les espaces de travail, pour un script de provisionnement. La lecture seule suffit à une suite de tests.
3. Où. Cochez les espaces de travail que la clé atteint, au moins un, ou choisissez tous les espaces, ceux que vous créerez plus tard compris.
4. Une durée. 30, 90, 180 ou 365 jours. Passé cette date, la clé cesse de marcher ; vous pouvez la remplacer avant.

Le secret s'affiche une seule fois, juste après la création. Nous n'en gardons qu'une empreinte : ni vous ni nous ne pouvons le retrouver ensuite. Copiez-le directement dans les secrets de votre CI.

L'utiliser

Un en-tête Authorization, et c'est tout :

curl -H "Authorization: Bearer fk_votre_cle" \
  https://api.facteur.eu/v1/inboxes

La clé se passe uniquement en Bearer. Le schéma Basic n'existe pas, et les adresses de l'API ne portent pas de préfixe de version.

Comptez 600 requêtes par minute et par clé. Au-delà, la réponse est 429 RATE_LIMITED, avec l'en-tête Retry-After.

Chaque route, sa permission et ses refus sont dans la référence d'API que l'API publie elle-même : https://api.facteur.eu/openapi.json en anglais et https://api.facteur.eu/openapi.fr.json en français. Le portail de documentation pour développeurs n'est pas encore en ligne.

Choisir la portée

Une clé répond séparément à deux questions, ce qui vous permet de n'en donner que peu à la fois.

Ce qu'elle peut faire, en quatre portées et deux familles :

Portée	Ce qu'elle ouvre
ws:read	Lire les messages des espaces visés
ws:write	Y créer et supprimer des inboxes
org:read	Lister les espaces de travail, et voir qui accède à chacun
org:write	En créer un, le renommer, le marquer, et ajouter ou retirer les collègues qui y accèdent

Où elle peut le faire : tous vos espaces de travail, ou seulement ceux que vous nommez.

Écrire implique lire dans une famille, et rien ne traverse les familles. org:write ne donne donc pas accès à votre courrier : un script qui provisionne des espaces n'a pas à lire les messages qui s'y trouvent.

Si vous choisissez « tous les espaces », la portée inclut aussi ceux que vous créerez plus tard. Une liste figée à la création serait une clé qui cesse silencieusement de couvrir vos nouveaux espaces.

Une clé ne dépasse jamais la personne qui la crée. Les permissions org: et le choix « tous les espaces » demandent le droit de gérer les espaces de travail, et chaque espace coché doit être un espace que vous atteignez vous-même.

Ce qu'une clé n'atteint jamais

Quelle que soit sa portée.

Ce que la clé tente	Le refus	Ce que vous faites
Créer, remplacer ou révoquer une clé	Aucune route	Passez par l'application. Une clé volée qui se remplace elle-même rendrait sa révocation sans effet
Toucher votre compte : mot de passe, second facteur, passkeys	Aucune route	Une clé fuitée ne prend pas le compte
Écrire alors qu'elle est en lecture seule	403 API_KEY_PERMISSION_MISSING	La réponse nomme la permission manquante (permission)
Lister les espaces sans org:*	403 API_KEY_PERMISSION_MISSING	Créez une clé avec org:read
Faire entrer quelqu'un dans l'organisation, payer, écrire une destination d'alerte	Aucune route	Invitez depuis l'application. Voir Membres et sièges
Supprimer un espace de travail	403 API_KEY_CANNOT_DELETE_WORKSPACE	Supprimez depuis l'application : aucune clé, quelle que soit sa permission, n'a ce droit
Lire le courrier d'un espace hors de sa portée	404	La clé visant « recette » ne lit pas l'espace principal. C'est la même frontière que celle des membres, voir Espaces de travail

Une session d'assistance ne peut pas créer de clé non plus, même avec votre accord explicite : la clé serait ensuite indiscernable d'une clé que vous auriez créée vous-même.

Remplacer sans coupure

Remplacer crée une clé neuve et laisse l'ancienne vivre 24 heures par défaut. La nouvelle reprend les permissions et les espaces de l'ancienne, dure 90 jours, et porte le nom de l'ancienne suivi de « (replaced » et de la date du jour. Déployez le nouveau secret, regardez passer un build vert, et l'ancienne s'éteint seule. Une rotation qui coupe est une rotation que personne ne fait.

Une clé déjà révoquée ne se remplace pas : cela la garderait vivante quelques heures de plus, ce qui annulerait la révocation (409 API_KEY_REVOKED). Une clé échue se remplace.

Révoquer

Immédiat, sans fenêtre de cache : l'appel suivant échoue, y compris celui d'un pipeline en cours.

Avant de révoquer, lisez la colonne « Dernière utilisation » : elle vous dit si la clé sert encore.

Ensuite, le refus distingue trois cas, parce que les gestes qu'ils demandent sont différents :

Code	Ce que ça veut dire	Ce que vous faites
API_KEY_REVOKED	Quelqu'un l'a retirée	Créez-en une nouvelle
API_KEY_EXPIRED	Elle a atteint sa date	Remplacez-la
API_KEY_UNKNOWN	Cette clé n'a jamais existé	Vérifiez ce que votre CI envoie

Ce sont trois réponses 401.

Supprimer un espace visé par une clé

Refusé, avec 409 WORKSPACE_HAS_ACTIVE_KEYS et le nom des clés qui bloquent.

Deux gestes possibles avant de réessayer : révoquer la clé, ou retirer cet espace de sa portée. Une clé déjà révoquée ou expirée ne bloque rien, puisqu'elle n'ouvre plus rien.

Provisionner un espace de travail par branche

C'est ce que org:write sert à faire :

# Ouvrir un espace pour la branche courante
curl -X POST https://api.facteur.eu/v1/workspaces \
  -H "Authorization: Bearer fk_votre_cle" \
  -H "content-type: application/json" \
  -d '{"name": "recette-PR-1234"}'

Deux choses à savoir :

• L'espace créé n'entre pas dans la portée de la clé. Une clé ne s'élargit pas elle-même. Si vos tests doivent lire le courrier de ce nouvel espace, visez « tous les espaces » à la création de la clé.
• Le plafond du plan s'applique. Un plan qui ne vend pas d'espace de plus répond 402 WORKSPACE_LIMIT_REACHED.

Gérer qui accède à un espace de travail

Une clé portant org:write peut lister les membres d'un espace de travail, en ajouter un et en retirer un.

Cela ne fait entrer personne dans votre organisation. La personne que vous nommez doit déjà en être membre ; toute autre est refusée avec NOT_AN_ORGANIZATION_MEMBER. Ce qui change, c'est quels espaces un collègue déjà présent peut ouvrir.

Inviter reste l'acte qu'une clé n'accomplit jamais.

Limites connues

• Pas de restriction d'adresse IP. Une clé marche depuis n'importe quelle adresse : il n'existe pas de liste d'adresses autorisées, pour les runners qui sortent par une adresse fixe.