# Clés API

> Clés sk_ (format, portée, droits, erreurs) et opérations /api/app-keys des clés wsk_ que vos clients utilisent pour appeler votre wakapp.

Une [clé API](/v1.0/glossaire#clé-api) authentifie les appels d'un serveur, sans utilisateur connecté. Elle s'envoie dans l'en-tête `x-api-key`. Cette page décrit ce qu'une clé permet ; la création et la gestion des clés sont décrites dans [Clés API](/v1.0/cles-api). Les clés `wsk_` que les organismes clients utilisent pour appeler **votre wakapp** sont décrites plus bas, dans [Clés API de votre wakapp](#clés-api-de-votre-wakapp).

## Obtenir une clé

Les clés API sont créées par l'équipe Wakastart. Pour en obtenir une, indiquez l'application, l'environnement, le client et le profil voulus. La clé complète ne vous est montrée qu'**une seule fois** : rangez-la aussitôt dans un secret de votre service. Wakastart n'en conserve qu'une empreinte et ses 10 premiers caractères, qui permettent de la reconnaître.

L'API publique n'expose aucun endpoint de création, de lecture ou de révocation de clé `sk_`.

## Format

| Élément | Valeur |
|---|---|
| Préfixe | `sk_` |
| Longueur | `sk_` suivi de 40 caractères (lettres, chiffres, `-` et `_`) |
| En-tête | `x-api-key: sk_…` |

Un en-tête `x-api-key` dont la valeur ne commence pas par `sk_` n'est pas reconnu comme une clé de votre organisation.

## Ce que porte une clé

| Propriété | Effet sur les appels |
|---|---|
| Application | La clé compte comme émise pour cette application ; elle est refusée sur toute autre application |
| Environnement | `dev`, `staging` ou `prod`. Les appels s'exécutent dans cet environnement, que vous ne fournissez jamais : les utilisateurs lus ou modifiés sont ceux de cet environnement, une invitation créée par la clé vaut pour cet environnement. Un paramètre `env`, `envType` ou `envs` est refusé (`400`) |
| Client | Les listes sont limitées à ce client, quels que soient les filtres envoyés |
| Profil | Les droits applicatifs de la clé sont ceux de ce profil, lus dans la matrice profils × droits de l'environnement de la clé |
| Niveau d'administration | Niveau minimal exigé par les endpoints, au plus celui de la personne qui a créé la clé |
| Adresses IP autorisées | Optionnel : un appel depuis une autre adresse est refusé |
| Date d'expiration | Optionnelle : après cette date, la clé est refusée |
| État | Une clé désactivée ou révoquée est refusée immédiatement |

Une clé peut être liée à un compte utilisateur ou être un **compte technique**, sans utilisateur. Une clé de compte technique n'a pas d'identité de personne : `GET /api/me` lui répond `404` `Utilisateur non trouvé`.

## Portée des listes

Pour un appel par clé, l'API remplace les filtres de portée de la requête (`customerWid`, `networkWid`…) par la portée de la clé, dans cet ordre :

1. le client de la clé ;
2. à défaut, son réseau, pour un compte technique de niveau Administrateur réseau ;
3. à défaut, son application.

Une clé sans aucune de ces portées ne peut rien lister : `403` `API key without tenant scope cannot list tenant data`.

## Endpoints qui exigent une clé

La plupart des endpoints acceptent indifféremment un jeton ou une clé. Les endpoints suivants n'acceptent **que** une clé :

| Endpoint | Page |
|---|---|
| `GET /api/legal-documents` | [Documents légaux](/v1.0/reference-api/documents-legaux) |
| `GET /api/legal-documents/default` | [Documents légaux](/v1.0/reference-api/documents-legaux) |
| `POST /api/legal-documents/{id}/render` | [Documents légaux](/v1.0/reference-api/documents-legaux) |

À l'inverse, les endpoints de paiement de l'utilisateur final (`/api/billing/*`) exigent l'identité d'un utilisateur de l'application ; une clé de compte technique n'y convient pas.

## Exemple

```bash
curl -s "https://api.wakastart.app/api/config/teams" \
  -H "x-api-key: sk_test_exemple"
```

```ts
const WAKASTART_API_KEY = process.env.WAKASTART_API_KEY; // lue dans un secret, jamais dans le code

const res = await fetch("https://api.wakastart.app/api/config/teams", {
  headers: { "x-api-key": WAKASTART_API_KEY! },
});
if (res.status === 401) throw new Error("Clé API refusée : vérifiez sa validité");
const { data } = await res.json();
```

N'envoyez pas d'en-tête `Authorization` dans la même requête : la clé serait ignorée.

## Erreurs

| Statut | Message | Cause |
|---|---|---|
| `401` | `Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header)` | Clé inconnue, inactive, expirée ou utilisée depuis une adresse IP non autorisée |
| `401` | `Cle API manquante (header x-api-key)` | L'endpoint exige une clé et la requête n'en porte pas |
| `401` | `Cle API utilisateur invalide ou expiree` | L'endpoint exige une clé et celle envoyée est refusée |
| `403` | `API key without tenant scope cannot list tenant data` | Clé sans client, réseau ni application |
| `403` | `Droit applicatif requis : <code>` | Le profil de la clé ne porte pas le droit |
| `403` | `Access denied: token authorized party does not match the target application` | Clé d'une autre application |
| `400` | `Environment is deduced from the caller and cannot be provided` | Paramètre `env`, `envType` ou `envs` envoyé |
| `403` | `Environment cannot be deduced: API key has no environment` | Clé sans environnement |

## Bonnes pratiques

- Une clé par service et par environnement, pour pouvoir en révoquer une sans couper les autres. Les droits d'une clé `dev` ou `staging` se règlent dans la matrice de son environnement, indépendamment de la production.
- Le profil le plus restreint possible : seulement les droits dont le service a besoin.
- Une date d'expiration et une liste d'adresses IP quand votre service sort par des adresses fixes.
- En cas de fuite, demandez la révocation immédiate de la clé, puis remplacez-la.

## Clés API de votre wakapp

:badge[Bêta]{type=beta} Ces opérations sont en cours de déploiement et ne répondent pas encore.

Les clés `wsk_` permettent au système d'information d'un organisme client d'appeler l'API **de votre wakapp**. Elles portent des droits de votre catalogue et aucun droit sur Wakastart : une clé `wsk_` envoyée à l'API publique reçoit un `401`. Concepts et guides : [Clés API de votre wakapp](/v1.0/cles-api/cles-api-de-votre-wakapp).

Deux familles d'opérations, avec deux authentifications :

| Opérations | Authentification |
|---|---|
| Vérification par votre wakapp : `introspect`, `user-context` | Clé `sk_` de votre wakapp dans `x-api-key`, **sans** `Authorization`. Wakastart en déduit votre application et votre environnement |
| Gestion des clés : création, liste, lecture, modification, rotation, révocation | Jeton de l'utilisateur dans `Authorization: Bearer` (et son `x-enriched-token` si vous l'avez), **sans** clé `sk_` ; une clé seule est refusée (`403 API_KEY_CANNOT_MANAGE_KEYS`). Aucun droit Wakastart n'est exigé : le plafond et la portée sont vérifiés par Wakastart |

Pour la gestion, l'application et l'environnement sont **déduits du jeton** : l'application pour laquelle il a été émis, l'environnement de la session. Toutes ces opérations sont bornées à cette application et à cet environnement. `appWid` ou `envType` envoyé et différent répond `403 APP_SCOPE_MISMATCH` ; un jeton qui ne désigne aucune application cliente répond `403 APP_NOT_RESOLVED` ; une clé d'une autre application ou d'un autre environnement répond `404`.

Les erreurs ont le format habituel, avec un **code stable dans `message`** et parfois un objet `details` :

```json
{
  "statusCode": 403,
  "message": "RIGHTS_EXCEED_CEILING",
  "error": "Forbidden",
  "details": { "missing": ["formations.delete"] }
}
```

La liste des codes est dans [Codes d'erreur](/v1.0/codes-d-erreur#clés-api-des-wakapps).

### L'objet clé de wakapp

| Champ | Type | Description |
|---|---|---|
| `wid` | chaîne | Identifiant public de la clé. Jamais le secret |
| `name` | chaîne | Nom |
| `description` | chaîne ou `null` | Description |
| `type` | chaîne | `USER_BOUND` (liée à un utilisateur) ou `TECHNICAL` |
| `customer` | objet | Organisme de la clé : `{ wid, name }` |
| `app` | objet | Application : `{ wid, name }` |
| `envType` | chaîne | `dev`, `staging` ou `prod` |
| `owner` | objet ou `null` | Clé liée : son utilisateur, `{ wid, label }`. Clé technique : `null` |
| `createdBy` | objet | Créateur : `{ wid, label, deleted }` ; `deleted` vaut `true` si son compte a été supprimé |
| `rights` | tableau de chaînes | Droits inscrits sur la clé |
| `inoperantRights` | tableau de chaînes | Droits inscrits mais sans effet : l'utilisateur ne les détient plus, ou ils ne sont plus disponibles dans l'environnement |
| `status` | chaîne | `ACTIVE`, `SUSPENDED` ou `REVOKED` |
| `expiresAt` | chaîne ISO 8601 ou `null` | Échéance ; `null` pour une validité infinie. Une clé échue est refusée |
| `lastUsedAt` | chaîne ISO 8601 ou `null` | Dernier usage accepté |
| `createdAt` | chaîne ISO 8601 | Date de création |

Le secret (`secret`, commençant par `wsk_`) n'est renvoyé qu'à la création et à la rotation.

### Vérifier une clé

::endpoint{method="POST" path="/api/app-keys/introspect"}

**Authentification** : clé `sk_` de votre wakapp, sans `Authorization`. Appelée par votre wakapp à chaque requête d'un client.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `secret` | chaîne | oui | Secret `wsk_` présenté par le client |

```bash
curl -s -X POST https://api.wakastart.app/api/app-keys/introspect \
  -H "x-api-key: sk_test_exemple" \
  -H 'Content-Type: application/json' \
  -d '{ "secret": "wsk_exemple3kTq9" }'
```

**Réponse `200`**, toujours, que la clé soit valide ou non :

```json
{
  "active": true,
  "key_id": "K7hq2P",
  "type": "TECHNICAL",
  "owner": null,
  "customer": { "wid": "ALPHA1", "name": "Organisme Alpha" },
  "app": "APPEX1",
  "env": "prod",
  "rights": ["formations.read", "participants.invite"],
  "exp": null
}
```

| Champ | Description |
|---|---|
| `active` | `true` si la clé est acceptée ; sinon la réponse est `{ "active": false }`, sans autre champ |
| `key_id` | Identifiant public de la clé, à écrire dans vos journaux |
| `type` | `USER_BOUND` ou `TECHNICAL` |
| `owner` | Clé liée : `{ "wid": "…" }` de son utilisateur. Clé technique : `null` |
| `customer` | Organisme de la clé. Limitez toutes vos requêtes à cet organisme |
| `app`, `env` | WID de votre application et environnement de la clé |
| `rights` | Droits **effectifs** : pour une clé liée, croisés avec les droits actuels de l'utilisateur ; pour une clé technique, bornés par les droits que l'organisme détient encore |
| `exp` | Expiration en secondes depuis l'epoch, `null` pour une validité infinie |
| `context_token` | Facultatif : [jeton de contexte](/v1.0/cles-api/jeton-de-contexte) « clé client », valable 60 secondes |

`{ "active": false }` couvre une clé inconnue, révoquée, expirée, suspendue, d'une autre application, d'un autre environnement, ou dont l'organisme n'a plus l'application. Ne gardez jamais une réponse positive en cache.

**Erreurs** : `403 CALLER_APP_KEY_REQUIRED` sans clé `sk_` valide, `429` au-delà de la limite de débit, `503 APP_KEYS_UNAVAILABLE` si Wakastart ne peut pas traiter la demande. Si Wakastart ne peut pas signer de contexte, la réponse n'a pas de `context_token`.

### Obtenir un contexte utilisateur

::endpoint{method="POST" path="/api/app-keys/user-context"}

**Authentification** : clé `sk_` de votre wakapp, sans `Authorization`. Renvoie un [jeton de contexte](/v1.0/cles-api/jeton-de-contexte) « utilisateur », pour agir sur Wakastart avec votre clé au nom d'un utilisateur de votre wakapp.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `userToken` | chaîne | oui | Jeton d'accès Keycloak de l'utilisateur, émis pour votre wakapp |

```bash
curl -s -X POST https://api.wakastart.app/api/app-keys/user-context \
  -H "x-api-key: sk_test_exemple" \
  -H 'Content-Type: application/json' \
  -d '{ "userToken": "eyJhbGciOiJSUzI1NiJ9.exemple" }'
```

**Réponse `200`** :

```json
{ "context_token": "eyJhbGciOiJFZERTQSJ9.exemple", "exp": 1798790460 }
```

**Erreurs**

| Statut | Code |
|---|---|
| `401` | `USER_TOKEN_INVALID` : jeton refusé (signature, expiration) ou identité ambiguë |
| `403` | `AZP_MISMATCH` : jeton émis pour une autre application |
| `403` | `USER_TOKEN_ENV_MISMATCH` : jeton d'un autre environnement que votre clé `sk_` |
| `403` | `USER_NOT_MEMBER` : utilisateur ou organisme inactif, ou sans accès à l'application |
| `503` | `CONTEXT_SIGNING_UNAVAILABLE` : Wakastart ne peut pas signer de contexte pour le moment |

### Présenter un contexte

Joignez le jeton de contexte à un appel de l'API publique dans l'en-tête `X-WakaStart-Context`, avec votre clé `sk_` dans `x-api-key` et **sans** en-tête `Authorization`. Il vaut 60 secondes au plus. L'exigence de contexte est réglée par type d'action et par application (`observe`, `preferred`, `required`, `bound`) : voir [Jeton de contexte](/v1.0/cles-api/jeton-de-contexte#modes-par-action). Les refus sont listés dans [Codes d'erreur](/v1.0/codes-d-erreur#jeton-de-contexte).

### Créer une clé

::endpoint{method="POST" path="/api/app-keys"}

**Qui** : clé liée, tout utilisateur actif qui a accès à l'application dans cet environnement, pour lui-même ; clé technique, un administrateur de l'organisme.

| Champ | Type | Obligatoire | Contraintes | Description |
|---|---|---|---|---|
| `type` | chaîne | oui | `USER_BOUND` ou `TECHNICAL` | Type de clé |
| `name` | chaîne | oui | — | Nom |
| `description` | chaîne | non | — | Description |
| `rights` | tableau de chaînes | oui | Droits du catalogue, sous le plafond de l'appelant | Droits accordés |
| `validity` | chaîne | non | `30d`, `90d`, `1y`, `infinite` | Validité ; `1y` par défaut |
| `customerWid` | chaîne | pour une clé technique | — | Organisme de la clé technique |

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

**Réponse `201`** : l'objet clé et son `secret`, renvoyé cette seule fois.

### Lister les clés

::endpoint{method="GET" path="/api/app-keys"}

**Qui** : le propriétaire de ses clés liées, les administrateurs de l'organisme pour les clés de leur portée. Renvoie les clés de l'application et de l'environnement du jeton, jamais de secret.

| Paramètre de requête | Type | Défaut | Description |
|---|---|---|---|
| `mine` | booléen | — | `true` : seulement les clés liées à l'appelant |
| `customerWid` | chaîne | — | Organisme |
| `type` | chaîne | — | `USER_BOUND` ou `TECHNICAL` |
| `status` | chaîne | — | `ACTIVE`, `SUSPENDED` ou `REVOKED` |
| `limit` | entier | 500 | Taille de page, 500 au plus |
| `offset` | entier | 0 | Décalage |

Réponse : `{ "data": [Clé…], "total": 12 }`. `total` compte toutes les clés visibles, pas seulement la page.

### Lire les droits attribuables

::endpoint{method="GET" path="/api/app-keys/assignable-rights"}

Droits que l'appelant peut donner à une clé : ceux du catalogue de l'application disponibles dans l'environnement, qu'il détient lui-même. Paramètres : `type` (`USER_BOUND` ou `TECHNICAL`) et, pour une clé technique, `customerWid` ; un organisme hors de la portée d'administration de l'appelant répond `404`.

Réponse : `{ "data": [{ "code": "formations.read", "name": "Lire les formations", "category": "Formations" }] }`. Cette liste sert à l'affichage : le plafond est revérifié à la création.

### Lire une clé

::endpoint{method="GET" path="/api/app-keys/{wid}"}

**Qui** : le propriétaire, les administrateurs de l'organisme. Réponse : l'objet clé. Une clé hors de la portée de l'appelant répond `404`.

### Modifier une clé

::endpoint{method="PATCH" path="/api/app-keys/{wid}"}

**Qui** : le propriétaire, les administrateurs de l'organisme. Le plafond s'applique à `addRights` ; retirer un droit est toujours permis.

| Champ | Type | Description |
|---|---|---|
| `name` | chaîne | Nouveau nom |
| `description` | chaîne | Nouvelle description |
| `addRights` | tableau de chaînes | Droits à ajouter |
| `removeRights` | tableau de chaînes | Droits à retirer |

Le type, l'organisme, l'application et l'environnement ne se modifient pas (`400 IMMUTABLE_FIELD`). Une clé révoquée ne se modifie plus (`409 KEY_REVOKED`).

### Faire tourner le secret

::endpoint{method="POST" path="/api/app-keys/{wid}/rotate"}

**Qui** : 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.

**Réponse `200`** : l'objet clé et son nouveau `secret`, renvoyé une seule fois. L'ancien secret reste valable 7 jours au plus, jamais au-delà de l'échéance de la clé. 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.

### Révoquer une clé

::endpoint{method="DELETE" path="/api/app-keys/{wid}"}

**Qui** : le propriétaire, les administrateurs de l'organisme. Corps facultatif : `{ "reason": "plus utilisée" }`.

**Réponse `204`**. La révocation est immédiate : la clé est refusée dès l'introspection suivante et reste consultable au statut `REVOKED`.

### Limites de débit

| Opération | Limite par défaut |
|---|---|
| `POST /api/app-keys/introspect` | 3 000 appels par minute |
| `POST /api/app-keys/user-context` | 600 appels par minute |

Ces limites sont comptées par wakapp et par environnement de sa clé `sk_`, sur une fenêtre fixe d'une minute, et par instance du service Wakastart : chaque instance tient ses propres compteurs, la limite effective est donc multipliée par le nombre d'instances. Au-delà, la réponse est `429` avec l'en-tête `Retry-After`, en secondes.
