# Créer une clé d'API et brancher votre suite de tests · Facteur > Créer une clé, l'utiliser depuis une CI, la remplacer sans coupure et la révoquer. Ce qu'elle atteint, et ce qu'elle n'atteindra jamais. > https://facteur.eu/fr/aide/cles-api Rechercher dans l'aide Ctrl K Rechercher dans l'aide Tapez au moins deux caractères. # Créer une clé d'API et brancher votre suite de tests Créer une clé, l'utiliser depuis une CI, la remplacer sans coupure et la révoquer. Ce qu'elle atteint, et ce qu'elle n'atteindra jamais. Mis à jour le 22 août 2026 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é**](https://app.facteur.eu/settings/api-keys)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 : ```bash 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éeCe 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é tenteLe refusCe que vous faitesCréer, remplacer ou révoquer une cléAucune routePassez par [l'application](https://app.facteur.eu/settings/api-keys). Une clé volée qui se remplace elle-même rendrait sa révocation sans effetToucher votre compte : mot de passe, second facteur, passkeysAucune routeUne 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'alerteAucune routeInvitez depuis [l'application](https://app.facteur.eu/settings/users). Voir [Membres et sièges](/fr/aide/membres-et-sieges)Supprimer un espace de travail`403 API_KEY_CANNOT_DELETE_WORKSPACE`Supprimez depuis [l'application](https://app.facteur.eu/settings/workspaces) : aucune clé, quelle que soit sa permission, n'a ce droitLire 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](/fr/aide/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 : CodeCe que ça veut direCe que vous faites`API_KEY_REVOKED`Quelqu'un l'a retiréeCréez-en une nouvelle`API_KEY_EXPIRED`Elle a atteint sa dateRemplacez-la`API_KEY_UNKNOWN`Cette clé n'a jamais existéVérifiez ce que votre CI envoieCe 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 : ```bash # 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. Cet article ne répond pas à votre question ? Écrivez à l'équipe : elle saura de quel article vous venez. [ Écrire au support ](https://app.facteur.eu/support?article=cles-api)