# 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_.

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é 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](/v1.0/cles-api/cles-api-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

- [Obtenir une clé API](/v1.0/cles-api/obtenir-une-cle-api).
- [Référence des clés API](/v1.0/cles-api/reference).
- [Droits et profils](/v1.0/droits-et-profils).
- [Clés API de votre wakapp](/v1.0/cles-api/cles-api-de-votre-wakapp).
