Skip to Content
APIClés d'API

Clés d’API

Une clé d’API est un justificatif destiné à un programme plutôt qu’à une personne : un script d’intégration, un logiciel métier, une tâche planifiée. Contrairement à un jeton de session, elle ne s’obtient pas en saisissant un mot de passe et ne se périme pas d’elle-même au bout de quelques minutes.

Les clés se gèrent depuis Paramètres → onglet « API », dans l’encart « Clés d’accès API ». L’onglet porte sa propre phrase d’accueil, qui dit exactement son périmètre : « Gérez vos clés d’accès à l’API REST Stratt. »

Créer une clé

Ouvrir le formulaire

Dans l’encart « Clés d’accès API », le bouton « Nouvelle clé » déplie un champ unique.

Nommer la clé

Le champ attend un « Nom de la clé ». C’est la seule information demandée, et elle est obligatoire : le bouton de création reste inactif tant que le champ est vide.

Ce nom n’est pas décoratif. C’est la seule chose qui vous dira, dans six mois, ce qu’une clé fait tourner — et donc la seule chose qui vous permettra de la révoquer sans casser une intégration que vous auriez oubliée. Nommez d’après l’usage, pas d’après la personne : « Import mandats Astre nuit » vaut mieux que « clé Sophie ».

Créer, puis copier immédiatement

Le bouton « Créer » affiche la clé dans un encart qui prévient sans ambiguïté :

Copiez cette clé maintenant — elle ne sera plus affichée.

Le bouton « Copier » la place dans le presse-papiers.

La phrase est à prendre au mot. La clé n’est montrée qu’à cet instant. Elle n’est pas conservée en clair, et personne — pas même le support — ne peut la retrouver ensuite. Si vous fermez l’encart sans l’avoir copiée, il n’y a rien à récupérer : il faut créer une nouvelle clé et supprimer l’ancienne.

Ce que la liste affiche

Chaque clé existante apparaît sur une ligne portant :

  • son nom, tel que vous l’avez saisi ;
  • ses premiers caractères, suivis de points — de quoi reconnaître une clé dans un fichier de configuration sans la dévoiler ;
  • la mention « utilisée » suivie d’une date, lorsque la clé a déjà servi.

Cette date de dernier usage est l’information la plus utile de l’écran. Une clé qui n’a jamais servi est soit une clé oubliée, soit une intégration qui n’a jamais fonctionné ; une clé qui n’a pas servi depuis des mois est une clé à supprimer.

Faire expirer une clé

Une clé peut porter une échéance, au-delà de laquelle l’API la refuse. Ce n’est pas une suppression : la clé reste listée, elle cesse simplement d’ouvrir quoi que ce soit.

L’échéance se fixe à la création, et seulement par l’API. Le formulaire de l’onglet « API » ne demande qu’un nom ; une clé créée depuis l’interface n’a donc pas de terme. Pour en poser un, créez la clé par un appel portant le champ expires_at :

curl -s -X POST https://api.stratt.fr/api/v1/apidocs/api-keys \
  -H "Authorization: Bearer $STRATT_TOKEN" \
  -H "X-Organization-Id: $STRATT_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"label":"Import mandats Astre nuit","expires_at":"2027-01-01T00:00:00Z"}'

La réponse porte la clé en clair dans le champ key — c’est la seule fois.

Révoquer une clé

L’icône de corbeille en bout de ligne supprime la clé. L’effet est immédiat et définitif : l’appel suivant qui la présente est refusé, et il n’y a pas de confirmation à valider avant que la suppression ne soit faite. Vérifiez la ligne avant de cliquer.

Révoquez sans hésiter dès qu’une clé a pu fuiter : être copiée dans un ticket, poussée dans un dépôt, collée dans une conversation. Il n’y a pas de rotation partielle — on ne « change » pas une clé, on en crée une nouvelle, on bascule l’intégration, puis on supprime l’ancienne. Dans cet ordre.

Les routes

GET    /api/v1/apidocs/api-keys
POST   /api/v1/apidocs/api-keys
DELETE /api/v1/apidocs/api-keys/:id

La création accepte label (requis) et expires_at (optionnel). La réponse d’une création porte id, label, key, key_prefix, expires_at et created_at ; les listes ne portent jamais key.

Permissions requises

admin.manage — lister, créer et révoquer une clé relèvent de l’administration de l’organisation, parce qu’une clé vaut un accès à l’ensemble de ses données. Un compte qui ne porte pas cette permission voit l’onglet « API » le lui dire, et n’y trouve pas la liste.

Deux conséquences à en tirer :

  • la liste des clés est celle de l’organisation, pas celle du compte : ce que vous y voyez et révoquez peut appartenir à une intégration montée par quelqu’un d’autre ;
  • retirer un compte de l’organisation n’invalide pas les clés qu’il a créées. Voir la page Sécurité pour la marche à suivre au départ d’un agent.

Limites connues

  • Le mode programmatique n’est pas encore en service. Une clé se crée, se nomme, se liste et se révoque — tout ce que décrit cette page fonctionne. En revanche, présenter une clé à la place d’un jeton de session sur une route métier n’est pas encore pris en charge par l’API. Si vous construisez une intégration, appuyez-la sur un jeton de session et signalez votre besoin au support, qui vous dira où en est cette voie.
  • Pas d’échéance depuis le formulaire, et la liste n’affiche pas l’échéance d’une clé qui en porte une : il faut interroger la route de liste pour la relire.
  • Pas de récupération d’une clé perdue, et pas de rotation : la création d’une nouvelle clé est le seul chemin.
  • Pas de restriction par adresse IP ni par périmètre : une clé ne se limite pas à certaines routes ni à certains réseaux. Son échéance et sa révocation sont les deux seuls leviers.
AuthentificationRéférence