# Clés API de votre wakapp

> Les clés wsk_ qu'un organisme client utilise pour appeler l'API de votre wakapp : types, droits, plafond, validité, rotation et révocation.

Les organismes clients de votre wakapp veulent souvent l'appeler depuis leur propre système d'information : lire leurs formations, créer des projets, inviter des participants. Wakastart crée, stocke, vérifie et révoque les clés qu'ils utilisent pour cela ; votre wakapp les applique, en demandant à Wakastart ce que vaut chaque clé reçue, puis en contrôlant ses droits comme pour un utilisateur.

:::important
Les clés API des wakapps sont en cours de déploiement et ne sont pas encore disponibles : l'onglet **Clés API de l'app** n'apparaît pas encore dans la console et les opérations `/api/app-keys` ne répondent pas encore. Cette page décrit le fonctionnement prévu.
:::

## Définition

Une clé de wakapp est l'équivalent d'un utilisateur de votre wakapp : elle porte une liste de droits pris dans le **catalogue de droits de votre application**, ceux que vous attribuez déjà à vos utilisateurs par les profils (voir [Droits et profils](/v1.0/droits-et-profils)). Elle ne donne **aucun droit sur Wakastart**.

Chaque clé est attachée, définitivement, à :

- **un organisme**, le client propriétaire : votre wakapp limite toutes ses réponses à cet organisme ;
- **une application**, la vôtre : une clé présentée à une autre wakapp est refusée ;
- **un environnement**, `dev`, `staging` ou `prod` : une clé `dev` présentée à votre wakapp de production est refusée.

### À ne pas confondre avec votre clé `sk_`

| | Clé `sk_` | Clé de votre wakapp |
|---|---|---|
| Utilisée par | Le serveur de votre wakapp | Le système d'information d'un organisme client |
| Pour appeler | L'API publique Wakastart | L'API de votre wakapp |
| Commence par | `sk_` | `wsk_` |
| Où elle se gère | Équipe Wakastart (voir [Obtenir une clé API](/v1.0/cles-api/obtenir-une-cle-api)) | Onglet **Clés API de l'app** de la console, ou depuis votre wakapp |
| Droits | Niveau d'administration et profil Wakastart | Droits du catalogue de **votre** application |

Une clé `wsk_` envoyée directement à l'API publique Wakastart est refusée avec un `401` : elle n'y a aucun droit.

## Pourquoi ça existe

Sans ce mécanisme, chaque wakapp devrait inventer ses propres clés, les stocker, les révoquer et les relier à ses utilisateurs. Wakastart connaît déjà les organismes, les utilisateurs et les droits de votre application : il gère le cycle de vie des clés et répond à une seule question de votre wakapp, « que vaut cette clé ? ». La révocation d'une clé ou le départ de son utilisateur prend ainsi effet dès l'appel suivant, sans rien développer de votre côté.

## Comment ça marche

### Deux types de clés

| Type | Valeur | Qui la crée | Droits à l'usage | Fin de vie |
|---|---|---|---|---|
| **Liée à un utilisateur** | `USER_BOUND` | Tout utilisateur qui a accès à l'application dans cet environnement, pour lui-même | Droits de la clé **croisés avec les droits actuels** de l'utilisateur, recalculés à chaque vérification | Suspendue si le compte est désactivé ; révoquée s'il est supprimé ou perd l'accès à l'application |
| **Technique** | `TECHNICAL` | Les administrateurs de l'organisme (niveau Administrateur client ou plus, avec autorité sur cet organisme) | Fixés à la création, puis bornés à chaque vérification par les droits que l'organisme détient encore | Survit au départ de son créateur ; les administrateurs de l'organisme en sont prévenus par e-mail |

L'organisme d'une clé liée est toujours celui du compte de son utilisateur. Le type, l'organisme, l'application et l'environnement d'une clé sont fixés à la création et ne changent jamais.

### Le plafond

Personne ne crée ni ne modifie une clé pour lui donner plus de droits qu'il n'en a lui-même. Wakastart le vérifie à la création et à chaque ajout de droits : chaque droit demandé doit figurer parmi les droits actuels de la personne qui agit, pour cette application et cet environnement. Sinon, la demande est refusée avec le code `RIGHTS_EXCEED_CEILING` et la liste des droits manquants.

- Retirer un droit est toujours permis à qui gère la clé.
- Une clé n'a pas de niveau d'administration, seulement des droits.
- Un droit supprimé de votre catalogue disparaît des clés qui le portaient, comme pour les utilisateurs.
- Sur une clé liée, un droit que l'utilisateur ne détient plus reste inscrit mais n'a aucun effet : il est signalé comme **droit inopérant**.

Pour un contrôle plus fin, ajoutez des droits à votre catalogue, par exemple `formations.read` et `formations.export` : vos utilisateurs peuvent aussi s'en servir. Il n'existe pas de droits par chemin et par verbe HTTP.

### Le secret

- Il est affiché **une seule fois**, à la création ou à la rotation. Wakastart n'en garde qu'une empreinte et ne peut pas le relire.
- Il commence par `wsk_`. Ce préfixe sert uniquement à repérer une clé publiée par erreur, dans un dépôt de code ou un ticket. Ne fondez aucune décision sur la forme du secret : seule la réponse de Wakastart fait foi.
- Le client l'envoie à votre wakapp dans un en-tête, en HTTPS. Par convention : `Authorization: Bearer <secret>`. Jamais dans une URL, jamais dans un journal.

### Validité, rotation et révocation

- **Validité** : 30 jours, 90 jours, 1 an (par défaut) ou infinie. Une clé sans échéance reste valide tant qu'elle n'est pas révoquée : réservez-la aux intégrations suivies de près.
- **Rotation** : un nouveau secret est émis et affiché une seule fois. L'ancien reste valable **7 jours au plus**, jamais au-delà de l'échéance de la clé, le temps que le client bascule. Une nouvelle rotation pendant ce délai coupe immédiatement le secret qui était déjà en sursis : seuls le nouveau secret et le précédent restent valides. Les droits, l'organisme, l'application, l'environnement et l'échéance ne changent pas.
- **Révocation** : immédiate et définitive. La clé est refusée dès l'appel suivant et reste visible, au statut révoqué, pour l'historique.

```mermaid
stateDiagram-v2
  [*] --> ACTIVE: création
  ACTIVE --> SUSPENDED: compte de l'utilisateur désactivé (clé liée)
  SUSPENDED --> ACTIVE: compte réactivé
  ACTIVE --> EXPIRED: échéance dépassée
  ACTIVE --> REVOKED: révocation, ou utilisateur supprimé
  SUSPENDED --> REVOKED: révocation
  REVOKED --> [*]
```

L'API ne connaît que trois statuts, `ACTIVE`, `SUSPENDED` et `REVOKED` : une clé dont l'échéance `expiresAt` est passée est refusée, et la console l'affiche **Expirée**.

### La vérification à chaque appel

À chaque appel d'un client, votre wakapp envoie le secret reçu à Wakastart, avec sa propre clé `sk_`. Wakastart répond si la clé est active et, si oui, avec son organisme et ses droits effectifs. Votre wakapp ne garde jamais une réponse positive en cache : c'est ce qui rend la révocation immédiate. Le détail est dans [Vérifier une clé de votre wakapp](/v1.0/cles-api/verifier-une-cle-de-votre-wakapp).

## Exemples

- **Un export comptable.** Un administrateur de l'Organisme Alpha crée une clé technique portant `formations.read`, valable un an. Le SI comptable de l'organisme lit chaque nuit ses formations, et seulement les siennes.
- **Un script personnel.** Une formatrice crée une clé liée à son compte pour automatiser ses inscriptions. Si son compte est désactivé, la clé est suspendue ; si elle perd le droit `participants.invite`, la clé le perd aussi.
- **Un départ.** Le créateur d'une clé technique quitte l'organisme : la clé continue de fonctionner, et les administrateurs de l'organisme sont prévenus par e-mail pour décider de la garder ou de la révoquer.

## Pour aller plus loin

- [Gérer les clés de votre wakapp dans la console](/v1.0/cles-api/gerer-les-cles-de-votre-wakapp)
- [Vérifier une clé de votre wakapp](/v1.0/cles-api/verifier-une-cle-de-votre-wakapp)
- [Proposer les clés dans votre wakapp](/v1.0/cles-api/proposer-les-cles-dans-votre-wakapp)
- [Jeton de contexte](/v1.0/cles-api/jeton-de-contexte)
- [Référence API : clés de votre wakapp](/v1.0/reference-api/cles-api#clés-api-de-votre-wakapp)
