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.
This page has not been translated yet and is shown in French.
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). À 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.
curl -s https://api.wakastart.app/api/me \
-H "Authorization: Bearer $ACCESS_TOKEN"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). Renouvelez le jeton auprès de Keycloak avec le jeton de rafraîchissement avant son expiration.
Jeton enrichi
Le jeton enrichi est un jeton signé par Wakastart, obtenu en échange du jeton Keycloak avec POST /api/auth/enrich. L'API le vérifie localement, sans appel supplémentaire. Il expire en même temps que le jeton Keycloak dont il est issu.
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 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.
curl -s "https://api.wakastart.app/api/config/users?limit=5" \
-H "x-api-key: sk_test_exemple"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).
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 :
x-api-keycommençant parsk_, à condition que la requête ne porte pas d'en-têteAuthorization;x-enriched-token, si sa signature est valide ;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) |
GET /api/discovery/email | Relais de la recherche par e-mail de Discovery (voir Discovery) |
Le service Discovery est entièrement public.
Se déconnecter
/api/auth/logoutPublic, 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 |
curl -s -X POST https://api.wakastart.app/api/auth/logout \
-H "Content-Type: application/json" \
-d '{ "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.exemple" }'Réponse 200
{ "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 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.