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_.
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,stagingouprod; - 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é technique | Clé liée à un compte | |
|---|---|---|
| Appartient à | Aucune personne : le client | Un utilisateur |
| Usage | Backend, synchronisation, intégration | Script personnel d'un utilisateur |
| Niveau d'administration | Celui de la clé ; aucun s'il n'est pas fixé | Celui de la clé, sinon celui de l'utilisateur |
| Profil | Un profil Wakastart prévu pour les clés techniques | Un profil de l'application |
| Survit au départ d'une personne | Oui | Non : 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
- Votre serveur envoie la clé dans l'en-tête
x-api-key, sans en-têteAuthorization: si les deux sont présents, l'API utilise le jeton de l'en-têteAuthorizationet ignore la clé. - 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.
- 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.
- 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.readetusers.update, lit et met à jour les utilisateurs du client chaque nuit. - Inviter depuis votre parcours d'inscription. Une clé technique
proddont le profil porteinvitations.createdans la matrice de production envoie les invitations de l'environnement de production ; une cléstagingfait 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.