# Authentification de l'API

> Les trois façons d'authentifier un appel à l'API publique, la règle du jeton émis pour l'application et les erreurs d'authentification.

Chaque appel à l'API publique, sauf les rares endpoints publics signalés comme tels, doit porter l'identité de l'appelant. L'API accepte trois formes d'identité, envoyées chacune dans son propre en-tête.

## Méthodes acceptées

| Méthode | En-tête | Pour quoi faire | Droits pris en compte |
|---|---|---|---|
| Jeton Keycloak | `Authorization: Bearer <jeton>` | Appeler l'API au nom d'un utilisateur connecté, depuis votre front ou votre serveur | Niveau d'administration, droits applicatifs, droits d'équipe, rôles HDS |
| Jeton enrichi | `x-enriched-token: <jeton>` | Appels légers au nom d'un utilisateur, sans recalcul des droits à chaque requête | Niveau d'administration et rattachements seulement |
| Clé API | `x-api-key: sk_…` | Appels de serveur à serveur, sans utilisateur connecté | Niveau et droits du profil de la clé |

Nous recommandons le jeton Keycloak pour tout appel fait au nom d'un utilisateur : c'est la seule forme qui transporte tous ses droits.

## Jeton Keycloak

Le jeton d'accès que Keycloak délivre à votre application à la fin de la connexion de l'utilisateur (voir [Connecter vos utilisateurs](/v1.0/demarrer/connecter-vos-utilisateurs)). À chaque appel, l'API le fait vérifier par Wakastart et calcule les droits de l'utilisateur pour votre application et pour l'environnement de la session.

```bash
curl -s https://api.wakastart.app/api/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```ts
const response = await fetch("https://api.wakastart.app/api/me", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
if (!response.ok) throw new Error(`API ${response.status}`);
const me = await response.json();
```

Un jeton expiré ou illisible n'est pas refusé en tant que tel : l'appel est traité comme anonyme, et tout endpoint protégé répond `401` (voir [Erreurs d'authentification](#erreurs-dauthentification)). Renouvelez le jeton auprès de Keycloak avec le jeton de rafraîchissement avant son expiration.

## Jeton enrichi

Le [jeton enrichi](/v1.0/glossaire#jeton-enrichi) est un jeton signé par Wakastart, obtenu en échange du jeton Keycloak avec [`POST /api/auth/enrich`](/v1.0/reference-api/jeton-et-me#enrichir-un-jeton-keycloak). L'API le vérifie localement, sans appel supplémentaire. Il expire en même temps que le jeton Keycloak dont il est issu.

```bash
curl -s https://api.wakastart.app/api/me \
  -H "x-enriched-token: $ENRICHED_TOKEN"
```

Le jeton enrichi porte l'identité de l'utilisateur, son niveau d'administration, son environnement de session et les identifiants courts de son propriétaire, de son réseau, de son client et de l'application. Il ne porte **pas** les droits applicatifs, les droits d'équipe ni les rôles HDS.

:::important
Un endpoint qui exige un droit applicatif ou un rôle HDS refuse un appel authentifié par le seul jeton enrichi, avec `403`. Pour ces endpoints, envoyez le jeton Keycloak dans `Authorization`. Le jeton enrichi convient à `GET /api/me`, à la configuration de démarrage de l'application et aux endpoints de paiement de l'utilisateur final.
:::

Si l'utilisateur est désactivé, ses jetons enrichis sont révoqués immédiatement : l'API répond alors `401` avec le message `Token revoked`.

## Clé API

Une [clé API](/v1.0/glossaire#clé-api) commence par `sk_`. Elle est liée à une application, à un environnement, à un client et à un profil ; ses droits sont ceux de ce profil. Le détail de la portée d'une clé est dans [Clés API](/v1.0/reference-api/cles-api).

```bash
curl -s "https://api.wakastart.app/api/config/users?limit=5" \
  -H "x-api-key: sk_test_exemple"
```

```ts
const response = await fetch("https://api.wakastart.app/api/config/users?limit=5", {
  headers: { "x-api-key": process.env.WAKASTART_API_KEY! },
});
```

:::warning
Une clé API donne accès aux données de votre client sans aucune connexion. Ne l'envoyez jamais depuis un navigateur ou une application mobile, ne la commitez pas, et rangez-la dans un secret de votre service (voir [Variables et secrets](/v1.0/variables-et-secrets)).
:::

## Ordre de prise en compte

Si une requête porte plusieurs en-têtes, l'API retient le premier qui s'applique, dans cet ordre :

1. `x-api-key` commençant par `sk_`, **à condition** que la requête ne porte pas d'en-tête `Authorization` ;
2. `x-enriched-token`, si sa signature est valide ;
3. `Authorization: Bearer`.

N'envoyez donc qu'une seule méthode par requête. Une clé API accompagnée d'un en-tête `Authorization` est ignorée.

## Règle du jeton émis pour l'application

L'API vérifie que l'identité présentée a été émise **pour l'application appelée** : le client Keycloak qui a délivré le jeton (champ `azp`) doit être celui de l'application. Par convention, l'identifiant du client Keycloak d'une application est son identifiant court (WID), par exemple `EXAPP1`. Une clé API compte comme émise pour l'application à laquelle elle est liée.

Un jeton délivré pour une autre application, ou par le realm de la console Wakastart, est donc refusé, même si l'utilisateur existe dans les deux.

## Endpoints publics

Ces endpoints répondent sans aucune authentification :

| Endpoint | Rôle |
|---|---|
| `GET /api/healthz` | État de l'API |
| `POST /api/auth/enrich`, `POST /api/token/enrich` | Obtenir un jeton enrichi à partir d'un jeton Keycloak, qui fait office de preuve |
| `GET /api/invitations/verify/{token}`, `POST /api/invitations/accept/{token}` | Vérifier et accepter une invitation, le jeton d'invitation faisant office de preuve |
| `POST /api/auth/logout` | Fermer une session Keycloak, le refresh token faisant office de preuve (voir [Se déconnecter](#se-déconnecter)) |
| `GET /api/discovery/email` | Relais de la recherche par e-mail de Discovery (voir [Discovery](/v1.0/reference-api/discovery#depuis-lapi-publique)) |

Le service [Discovery](/v1.0/reference-api/discovery) est entièrement public.

## Se déconnecter

::endpoint{method="POST" path="/api/auth/logout"}

Public, limité à 10 requêtes par minute et par adresse IP. Ferme la session Keycloak à laquelle appartient le refresh token. L'API lit dans le jeton l'instance Keycloak, le realm et le client qui l'a émis : votre application n'a rien d'autre à fournir.

**Corps**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `refreshToken` | chaîne | oui | Refresh token de la session à fermer |
| `accessToken` | chaîne | non | Jeton d'accès de la même session. S'il est fourni, il doit venir du même émetteur et du même client que le refresh token |
| `clientId` | chaîne | non | Identifiant du client Keycloak. Inutile : il est déduit du jeton (claim `azp`). S'il est fourni, il doit être égal à celui du jeton |

```bash
curl -s -X POST https://api.wakastart.app/api/auth/logout \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.exemple" }'
```

**Réponse `200`**

```json
{ "success": true }
```

| Réponse | Sens |
|---|---|
| `{ "success": true }` | Session fermée |
| `{ "success": true, "message": "Session already terminated" }` | Le refresh token était déjà expiré ou invalidé |
| `{ "success": false, "message": "Logout failed: authentication server unreachable" }` | Keycloak injoignable |

**Erreurs**

| Statut | Message | Cause |
|---|---|---|
| `400` | `clientId does not match token` | `clientId` fourni et différent du client du jeton |
| `400` | `Invalid token issuer` | Jeton illisible ou sans émetteur reconnu |
| `400` | `tokens do not match` | `accessToken` et `refreshToken` viennent de deux sessions différentes |
| `429` | `ThrottlerException: Too Many Requests` | Limite de débit atteinte |
| `503` | — | Déconnexion momentanément impossible côté plateforme |

:::important
**Fermez la session locale de votre application quelle que soit la réponse** : succès, `success: false`, erreur `4xx` ou `5xx`, ou erreur réseau. Le guide [Déconnecter un utilisateur](/v1.0/authentification/deconnecter-un-utilisateur) montre la route serveur et le bouton correspondants.
:::

## Erreurs d'authentification

| Statut | Message | Cause | Résolution |
|---|---|---|---|
| `401` | `Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header)` | Aucune identité valide : en-tête absent, jeton expiré, clé inconnue, inactive ou expirée | Renouvelez le jeton, ou vérifiez la clé |
| `401` | `Cle API manquante (header x-api-key)` | L'endpoint n'accepte qu'une clé API et la requête n'en porte pas | Envoyez une clé dans `x-api-key` |
| `401` | `Cle API utilisateur invalide ou expiree` | L'endpoint n'accepte qu'une clé API et celle envoyée n'est pas valide | Vérifiez la clé, son état et sa date d'expiration |
| `401` | `Token revoked` | Le jeton enrichi a été révoqué, par exemple après la désactivation de l'utilisateur | Reconnectez l'utilisateur |
| `403` | `Access denied: token authorized party (azp) is missing` | Le jeton ne désigne aucune application | Utilisez le jeton délivré à votre application |
| `403` | `Access denied: application context is missing` | Le jeton ne porte pas l'application de l'utilisateur | Vérifiez que l'utilisateur a accès à l'application dans cet environnement |
| `403` | `Access denied: token authorized party does not match the target application` | Le jeton a été délivré pour une autre application | Utilisez le jeton délivré à votre application |
| `403` | `Niveau d'administration insuffisant. Requis: CustomerAdmin, Actuel: User` | Niveau d'administration trop faible pour l'endpoint | Faites l'appel avec un compte ou une clé de niveau suffisant |
| `403` | `Droit applicatif requis : users.read` | Le profil de l'appelant ne porte pas le droit | Ajoutez le droit au profil, ou utilisez le jeton Keycloak au lieu du jeton enrichi |
| `503` | `Auth check unavailable` | Pour une application HDS, la vérification de révocation est momentanément indisponible | Réessayez après quelques secondes |

La liste complète est dans [Codes d'erreur](/v1.0/codes-d-erreur#erreurs-dauthentification-et-daccès).
