# Proposer les clés dans votre wakapp

> Offrir à vos utilisateurs un écran « Mes clés API » dans votre wakapp : créer, lister, faire tourner et révoquer des clés en leur nom.

Votre wakapp peut proposer à ses utilisateurs un écran « Mes clés API », sans les envoyer dans la console Wakastart. Elle appelle alors les opérations de gestion des clés **au nom de l'utilisateur connecté**, avec son jeton : c'est Wakastart qui applique le plafond de ses droits et sa portée.

:::important
Les clés API des wakapps sont en cours de déploiement : les opérations `/api/app-keys` ne répondent pas encore. Ce guide décrit le fonctionnement prévu.
:::

## Avant de commencer

- L'utilisateur est connecté à votre wakapp et vous disposez de son jeton d'accès Keycloak, émis pour votre application (voir [Jetons et sessions](/v1.0/authentification/jetons-et-sessions)).
- Ces appels partent de votre serveur ou de votre BFF, avec le jeton de l'utilisateur, **jamais avec votre clé `sk_`** : une clé ne gère jamais de clés, et un appel avec la seule clé `sk_` est refusé (`403 API_KEY_CANNOT_MANAGE_KEYS`).

## Comment Wakastart borne les appels

N'envoyez ni votre application ni votre environnement : Wakastart les déduit du jeton de l'utilisateur. L'application est celle pour laquelle le jeton a été émis, l'environnement celui de la session. Une clé créée depuis votre wakapp vise donc toujours votre application, dans l'environnement où l'utilisateur est connecté, et la liste ne renvoie que les clés de cette application et de cet environnement.

| Situation | Réponse |
|---|---|
| `appWid` ou `envType` envoyé et différent de ceux du jeton | `403 APP_SCOPE_MISMATCH` |
| Le jeton ne désigne aucune application cliente (client inconnu de Wakastart, module, service, application de la plateforme) | `403 APP_NOT_RESOLVED` |
| Le jeton a été émis pour une autre application que celle du réseau de l'utilisateur | `403`, message `Access denied: token authorized party does not match the target application`, sans code stable |
| Clé d'une autre application, d'un autre environnement, ou hors de la portée de l'utilisateur | `404`, comme une clé inexistante |

## Afficher les droits attribuables

Les cases à cocher de votre écran ne doivent proposer que les droits que l'utilisateur peut donner : ceux du catalogue de votre application, disponibles dans l'environnement, qu'il détient lui-même.

```bash
curl -s "https://api.wakastart.app/api/app-keys/assignable-rights?type=USER_BOUND" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
```

```json
{
  "data": [
    { "code": "formations.read", "name": "Lire les formations", "category": "Formations" }
  ]
}
```

Pour une clé technique, passez `type=TECHNICAL` et `customerWid`. Cette liste sert à l'affichage : Wakastart revérifie le plafond à la création.

## Créer une clé

```bash
curl -s -X POST "https://api.wakastart.app/api/app-keys" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "USER_BOUND",
    "name": "Export compta",
    "description": "Lecture des formations par le SI comptable",
    "rights": ["formations.read"],
    "validity": "1y"
  }'
```

```ts
const res = await fetch("https://api.wakastart.app/api/app-keys", {
  method: "POST",
  headers: { Authorization: `Bearer ${userAccessToken}`, "Content-Type": "application/json" },
  body: JSON.stringify({ type: "USER_BOUND", name: "Export compta", rights: ["formations.read"], validity: "1y" }),
});
const created = await res.json();
```

Réponse attendue (`201`, extrait) :

```json
{
  "wid": "K7hq2P",
  "name": "Export compta",
  "type": "USER_BOUND",
  "rights": ["formations.read"],
  "status": "ACTIVE",
  "expiresAt": "2027-11-02T09:00:00.000Z",
  "secret": "wsk_exemple3kTq9"
}
```

Le `secret` n'est renvoyé **qu'une seule fois**. Affichez-le à l'utilisateur avec un bouton de copie, puis oubliez-le : ne le stockez pas, ne le journalisez pas.

Pour une clé technique, envoyez `"type": "TECHNICAL"` et `customerWid` ; l'utilisateur doit être administrateur de cet organisme.

## Lister, modifier, faire tourner et révoquer

| Action | Opération |
|---|---|
| Lister les clés de l'utilisateur | `GET /api/app-keys?mine=true`, paginée par `limit` (500 au plus) et `offset` ; réponse `{ data, total }` |
| Lire une clé | `GET /api/app-keys/{wid}` |
| Renommer, ajouter ou retirer des droits | `PATCH /api/app-keys/{wid}` avec `{ name?, description?, addRights?, removeRights? }` |
| Faire tourner le secret | `POST /api/app-keys/{wid}/rotate` ; nouveau secret renvoyé une seule fois, l'ancien reste valable 7 jours au plus |
| Révoquer | `DELETE /api/app-keys/{wid}`, corps facultatif `{ reason }`, réponse `204` |

Qui peut faire quoi :

| Action | Qui |
|---|---|
| Créer une clé liée | Tout utilisateur actif qui a accès à l'application dans cet environnement, pour lui-même |
| Créer une clé technique | Les administrateurs de l'organisme |
| Voir, modifier, révoquer | Le propriétaire d'une clé liée ; les administrateurs de l'organisme pour toutes les clés de leur portée |
| Faire tourner | Le propriétaire seul pour une clé liée ; un administrateur de l'organisme pour une clé technique, si les droits de la clé restent sous son propre plafond |

### Avec le kit

Le kit `@wakastellar/wakastart-keys` (voir [Vérifier une clé de votre wakapp](/v1.0/cles-api/verifier-une-cle-de-votre-wakapp#protéger-une-route-avec-le-kit)) enveloppe ces opérations :

```ts
import { createKey, listKeys, revokeKey, rotateKey } from "@wakastellar/wakastart-keys";

const user = { token: keycloakAccessToken, enrichedToken }; // ou keycloakAccessToken seul

const created = await createKey(user, {
  type: "USER_BOUND",
  name: "Export compta",
  rights: ["formations.read"],
  validity: "1y",
});
// created.secret : à afficher une seule fois, jamais stocké ni journalisé

await listKeys(user, { mine: true });
await rotateKey(user, created.wid); // l'ancien secret reste valable 7 jours au plus
await revokeKey(user, created.wid, "plus utilisée");
```

`getKey` et `updateKey` (`addRights`, `removeRights`) suivent le même modèle. Une erreur de Wakastart lève `WakaStartApiError`, avec `status`, `code` (par exemple `RIGHTS_EXCEED_CEILING`) et `details`.

## Vérifier le résultat

- La clé créée apparaît dans `GET /api/app-keys?mine=true`, au statut `ACTIVE`, sans secret.
- Une introspection de son secret par votre wakapp renvoie `"active": true` avec les droits accordés.
- Après `DELETE`, la même introspection renvoie `{ "active": false }`.

## Voir aussi

- [Clés API de votre wakapp](/v1.0/cles-api/cles-api-de-votre-wakapp)
- [Référence API : clés de votre wakapp](/v1.0/reference-api/cles-api#clés-api-de-votre-wakapp)
- [Codes d'erreur des clés de wakapp](/v1.0/codes-d-erreur#clés-api-des-wakapps)
