Skip to content

Fonctionnement des clés API

Clé technique ou liée à un compte, rattachement à une application, un environnement et un client, et calcul des droits d'une clé sk_.

ConceptDeveloper

This page has not been translated yet and is shown in French.

Une clé API est une identité de machine : elle remplace un utilisateur connecté pour les appels de serveur à serveur. Ce qu'elle peut faire ne dépend que de ce qui a été fixé à sa création : son application, son environnement, son client, son niveau d'administration et son profil.

Définition

Une clé API est une chaîne de la forme sk_ suivie de 40 caractères aléatoires. Elle est :

  • rattachée à une application : elle n'agit que sur cette application, comme un jeton émis pour elle ;
  • liée à un environnement : dev, staging ou prod ;
  • rattachée à un client : les opérations sur les utilisateurs et les équipes sont limitées à ce client ;
  • dotée d'un niveau d'administration et d'un profil, qui fixent ses droits ;
  • éventuellement limitée à une liste d'adresses IP et à une date d'expiration.

Il existe deux sortes de clés :

Clé techniqueClé liée à un compte
Appartient àAucune personne : le clientUn utilisateur
UsageBackend, synchronisation, intégrationScript personnel d'un utilisateur
Niveau d'administrationCelui de la clé ; aucun s'il n'est pas fixéCelui de la clé, sinon celui de l'utilisateur
ProfilUn profil Wakastart prévu pour les clés techniquesUn profil de l'application
Survit au départ d'une personneOuiNon : elle dépend du compte

Pour un backend, utilisez une clé technique.

Note

Ne confondez pas ces clés sk_, qui appellent l'API publique Wakastart, avec les clés de votre wakapp : celles-ci commencent par wsk_, permettent au système d'information d'un organisme client d'appeler l'API de votre wakapp, et portent des droits de votre catalogue, sans aucun droit sur Wakastart.

Pourquoi ça existe

Un serveur ne peut pas suivre une redirection vers Keycloak ni saisir un mot de passe. La clé API lui donne une identité stable, que l'on peut restreindre, tracer et révoquer sans toucher aux comptes des personnes.

Comment ça marche

Le secret n'est jamais conservé

À la création, Wakastart génère la clé, en calcule l'empreinte SHA-256 et ne garde que cette empreinte et les 10 premiers caractères, pour l'affichage. La clé complète n'est montrée qu'une seule fois, au moment de sa création. Une clé perdue ne se récupère pas : elle se remplace.

Ce qui se passe à chaque appel

  1. Votre serveur envoie la clé dans l'en-tête x-api-key, sans en-tête Authorization : si les deux sont présents, l'API utilise le jeton de l'en-tête Authorization et ignore la clé.
  2. L'API retrouve la clé par son empreinte et vérifie qu'elle est active, non expirée, et que l'adresse IP d'appel figure dans sa liste autorisée si elle en a une.
  3. Elle construit le contexte de l'appel : l'application de la clé, son environnement, son client, son niveau d'administration et les droits de son profil.
  4. L'opération vérifie le niveau et le droit qu'elle exige, puis s'exécute dans le périmètre du client de la clé.

La date et l'adresse IP du dernier usage sont enregistrées sur la clé.

Le calcul des droits

Les droits applicatifs d'une clé sont ceux de son profil, lus dans la matrice profils × droits de l'environnement de la clé. Le même profil peut donc donner des droits différents à une clé dev et à une clé prod. Une clé sans profil n'a aucun droit applicatif. Chaque opération de l'API publique exige un droit précis, par exemple users.read pour lister les utilisateurs ou invitations.create pour inviter, et souvent un niveau d'administration minimal, par exemple Administrateur client. Il faut les deux.

Une clé de niveau Administrateur réseau peut lire les clients de son réseau ; une clé de niveau Administrateur client reste limitée à son client.

L'environnement de la clé

Une clé appartient à un seul environnement, et cet environnement devient celui de chaque appel : vous ne le fournissez jamais. Les utilisateurs lus ou modifiés sont ceux de cet environnement, une invitation envoyée avec une clé dev est une invitation de l'environnement dev, et un paramètre d'environnement (env, envType, envs) envoyé à l'API publique est refusé avec un 400. Une clé sans environnement est refusée.

Utilisez donc une clé par environnement : une clé dev pour votre application de développement, une clé prod pour la production.

Ce qu'une clé ne change pas

Une clé ne se modifie pas après sa création, hormis son activation ou sa désactivation. Pour changer son profil, son niveau ou ses adresses autorisées, créez une nouvelle clé et révoquez l'ancienne.

Exemples

  • Synchroniser l'annuaire d'un client. Une clé technique de niveau Administrateur client, dont le profil porte users.read et users.update, lit et met à jour les utilisateurs du client chaque nuit.
  • Inviter depuis votre parcours d'inscription. Une clé technique prod dont le profil porte invitations.create dans la matrice de production envoie les invitations de l'environnement de production ; une clé staging fait de même pour la recette, avec les droits réglés en staging.
  • Un intégrateur de réseau. Une clé technique de niveau Administrateur réseau lit les clients et les utilisateurs de tout le réseau.

Pour aller plus loin