Authentification

Une clé d’API est l’identifiant que votre pipeline envoie à la place d’une connexion. Elle appartient à votre organisation et non à une personne : elle continue de marcher quand celle qui l’a créée s’en va. Elle cesse de marcher à une date choisie à sa création.

Envoyer la clé à chaque requête

Mettez-la dans l’en-tête Authorization, après Bearer :

curl --silent --show-error --fail-with-body \
  -H "Authorization: Bearer $FACTEUR_API_KEY" \
  https://api.facteur.eu/inboxes

Une clé commence par fk_. L’API écarte tout le reste avant de chercher quoi que ce soit.

Créer, renouveler et révoquer

Créer, modifier et révoquer une clé, c’est le travail d’une personne connectée à l’application Facteur, dans Paramètres, puis Clés d’API, et seulement d’un propriétaire ou d’un administrateur. Aucune clé ne peut créer ni terminer une clé, la sienne comprise, et l’API n’a pas de route pour cela.

À la création, vous choisissez une durée de 30, 90, 180 ou 365 jours, et toute clé expire. La clé s’affiche une seule fois, à sa création. Facteur en garde une empreinte, donc personne ne peut la montrer de nouveau. Après une révocation, l’appel suivant fait avec cette clé est refusé avec API_KEY_REVOKED.

Choisir ce que la clé peut faire

Une clé porte une ou plusieurs des quatre permissions, en deux familles :

Permission	Ce qu’elle ouvre
`ws:read`	Lire les inboxes, les messages et les demandes de numéro SMS des espaces de travail que la clé atteint.
`ws:write`	Tout ce que fait `ws:read`, et créer, modifier et supprimer des inboxes et des extracteurs, et demander un numéro SMS ou retirer la demande.
`org:read`	Lire la structure de l’organisation : ses espaces de travail et leurs membres, sa capacité et les destinations de ses alertes.
`org:write`	Tout ce que fait `org:read`, et créer et modifier des espaces de travail et leurs membres.

Dans une famille, écrire inclut lire. Les deux familles ne s’incluent jamais : une clé qui porte org:write seule crée des espaces de travail et ne lit aucun message.

Chaque opération de la référence nomme la permission qu’elle demande. Une clé qui ne l’a pas reçoit un 403 dont le code est API_KEY_PERMISSION_MISSING, et dont le membre permission nomme la permission manquante :

curl --silent --show-error --include \
  -X POST \
  -H "Authorization: Bearer $FACTEUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Un espace de travail"}' \
  https://api.facteur.eu/workspaces

Avec une clé qui ne porte que ws:read, cet appel répond 403, avec un en-tête WWW-Authenticate qui contient error="insufficient_scope" et la permission manquante en scope.

Choisir les espaces de travail que la clé atteint

Un espace de travail regroupe des inboxes et décide qui les atteint. À la création d’une clé, vous choisissez les espaces qu’elle atteint, ou tous, y compris ceux créés plus tard. Un espace que la clé n’atteint pas répond 404, comme s’il n’existait pas.

Ce qu’aucune clé ne fait

Rien de tout cela n’a de route sur l’API, quelles que soient les permissions de la clé :

inviter une personne dans une organisation ;
payer, changer d’offre ou de plafond de dépense, ou lire les factures ;
créer, modifier ou révoquer une clé d’API ;
créer, modifier ou supprimer les destinations des alertes. Une clé peut seulement les lister.

Une clé d’API ne supprime pas non plus un espace de travail : DELETE /workspaces/{slug} répond toujours 403 avec le code API_KEY_CANNOT_DELETE_WORKSPACE. Une personne le supprime depuis l’application.

Lire un refus qui dit comment s’authentifier

Un 401 porte un en-tête WWW-Authenticate. Il pointe vers le document qui décrit comment présenter une clé :

WWW-Authenticate: Bearer realm="Facteur API",
  resource_metadata="https://api.facteur.eu/.well-known/oauth-protected-resource"

Une clé présentée puis refusée ajoute error="invalid_token". Trois codes distinguent les raisons d’un refus, parce que chacune appelle une réparation différente :

Code	Ce qui s’est passé	Ce que vous faites
`API_KEY_UNKNOWN`	La clé n’a jamais existé.	Vérifiez ce que votre pipeline envoie vraiment.
`API_KEY_REVOKED`	Une personne l’a révoquée.	Créez une nouvelle clé.
`API_KEY_EXPIRED`	Elle a dépassé sa date.	Créez une nouvelle clé, et faites-le avant la date la prochaine fois.

Une requête sans aucune clé reçoit UNAUTHENTICATED. Le guide des erreurs liste tous les codes.