# Résoudre les problèmes de connexion

> Causes et solutions des erreurs rencontrées en intégrant la connexion d'une wakapp, de Discovery à /api/me, messages cités à l'identique.

Cette page part de ce que vous observez : une réponse de Discovery, un écran Keycloak, une erreur de l'API publique. Chaque symptôme indique sa cause probable, la solution et la façon de vérifier.

## Symptômes

- [Discovery répond 400 invalid_request](#discovery-répond-400-invalid_request)
- [Discovery répond 404 not_found](#discovery-répond-404-not_found)
- [Discovery renvoie une liste vide](#discovery-renvoie-une-liste-vide)
- [Keycloak affiche « Invalid parameter: redirect_uri »](#keycloak-affiche-invalid-parameter-redirect_uri)
- [L'échange du code renvoie invalid_grant](#léchange-du-code-renvoie-invalid_grant)
- [/api/me répond 401 Authentification requise](#apime-répond-401-authentification-requise)
- [L'API répond 403 Access denied](#lapi-répond-403-access-denied)
- [/api/me répond 404 ou 409](#apime-répond-404-ou-409)
- [L'enrichissement renvoie un objet vide](#lenrichissement-renvoie-un-objet-vide)
- [Le rafraîchissement renvoie Token is not active](#le-rafraîchissement-renvoie-token-is-not-active)
- [L'utilisateur est reconnecté sans mot de passe après la déconnexion](#lutilisateur-est-reconnecté-sans-mot-de-passe-après-la-déconnexion)
- [L'utilisateur reste connecté quand la déconnexion échoue](#lutilisateur-reste-connecté-quand-la-déconnexion-échoue)
- [Un build de dev connecte des comptes de production](#un-build-de-dev-connecte-des-comptes-de-production)
- [Une réponse 429 Too Many Requests](#une-réponse-429-too-many-requests)

## Discovery répond 400 invalid_request

```json
{ "statusCode": 400, "message": ["invalid_request: host is required (non-empty string, max 253 chars)"], "error": "Bad Request" }
```

**Cause** : `POST /discover/start-login` a été appelé sans `host`, ou avec un `host` vide. Un appel avec l'e-mail seul n'est plus accepté.

**Solution** : envoyez toujours le nom d'hôte complet de la page (`window.location.host`, ou l'en-tête `Host` côté serveur). Si plusieurs clients partagent ce nom d'hôte, ajoutez l'e-mail **en plus** du nom d'hôte (voir [Connecter par e-mail plusieurs clients sur un même nom d'hôte](/v1.0/authentification/connexion-multi-tenants-par-email)).

**Pour vérifier** : la même requête avec `host` renvoie `200`.

## Discovery répond 404 not_found

```json
{ "statusCode": 404, "message": "not_found", "error": "Not Found" }
```

**Cause** : aucun hôte IAM actif ne correspond exactement au `host` envoyé. Plus rarement : vous envoyez un ancien sous-domaine de réseau dont les hôtes IAM couvrent plusieurs environnements, le realm de l'environnement dev ou staging n'existe pas encore pour le réseau, ou le `customerWid` envoyé ne fait pas partie des candidats proposés.

**Solution** :

1. Envoyez le nom d'hôte seul : `mon-app.exemple.fr`, pas `https://mon-app.exemple.fr/`, ni `mon-app.exemple.fr:443`, ni des majuscules. Seul un hôte local garde son port : `monapp.localhost:3000`.
2. Envoyez le nom d'hôte complet, pas un sous-domaine extrait comme `reseau-exemple`.
3. Dans la console, ouvrez l'environnement, onglet **URLs & IAM**, section **Hôtes IAM**, et vérifiez que l'hôte existe et qu'il est actif. S'il manque, cliquez sur **Resynchroniser IAM** ou créez-le (voir [Déclarer les hôtes IAM et les redirect URIs](/v1.0/authentification/declarer-les-hotes-et-redirect-uris)).
4. Si vous venez de créer l'hôte, attendez 5 minutes : Discovery garde aussi les échecs en cache.

**Pour vérifier** : `POST /discover/start-login` renvoie `200` et une `keycloakUrl`.

## Discovery renvoie une liste vide

`GET /discover/email` répond `{ "users": [] }`.

**Cause** : l'adresse n'a aucun compte actif dans l'application et l'environnement désignés par `domain` ; ou `domain` ne correspond à aucun hôte IAM actif de votre application ; ou `domain` est absent, et seules les fiches de production sont cherchées. Une fiche n'existe que dans un environnement : un compte créé en prod n'est pas trouvé depuis votre front de dev.

**Solution** :

1. Envoyez toujours `domain`, avec le nom d'hôte de la page, par exemple `portail.mon-app.fr`.
2. Dans la console, ouvrez l'environnement visé, onglet **URLs & IAM**, et vérifiez que ce nom d'hôte est un hôte IAM actif.
3. Vérifiez que le compte existe chez le client **dans cet environnement**, et qu'il est actif.

**Pour vérifier** : la même requête renvoie au moins un compte, dont `network_realm_id` est le realm de l'environnement visé.

## Keycloak affiche Invalid parameter: redirect_uri

**Cause** : la `redirectUri` envoyée n'est pas déclarée dans le client Keycloak de l'environnement.

**Solution** :

1. Utilisez exactement `https://<nom d'hôte>/api/auth/callback`, sans barre oblique finale.
2. Vérifiez que l'hôte IAM correspondant existe dans le **même** environnement que celui de l'instance Keycloak affichée.
3. Pour une autre adresse (application mobile), ajoutez-la dans **Redirect URIs Keycloak**.

**Pour vérifier** : la page de connexion Keycloak s'affiche sans erreur.

## L'échange du code renvoie invalid_grant

Keycloak répond `400` avec `"error": "invalid_grant"`, par exemple `"error_description": "Code not valid"` ou `"Incorrect redirect_uri"`.

**Cause** : code déjà utilisé ou expiré (5 minutes), `redirect_uri` différente de celle de la demande, ou `code_verifier` qui ne correspond pas au `code_challenge`.

**Solution** :

1. N'échangez chaque code qu'une fois, dès sa réception.
2. Envoyez la même `redirect_uri` qu'à Discovery.
3. Envoyez le `code_verifier` brut conservé en session, sans le réencoder.
4. Vérifiez que l'échange vise l'émetteur lu dans la `keycloakUrl` (même instance, même realm) et le même `client_id`.

## /api/me répond 401 Authentification requise

```json
{
  "statusCode": 401,
  "message": "Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header)",
  "error": "Unauthorized",
  "timestamp": "2026-10-23T09:12:44.512Z",
  "path": "/api/me"
}
```

**Cause** : l'API n'a pu calculer aucun contexte pour ce jeton. Le jeton a expiré, n'est pas un jeton Keycloak valide, ou l'utilisateur n'a pas accès à l'application dans l'environnement de la session (aucun accès ni profil attribué, compte désactivé).

**Solution** :

1. Rafraîchissez la session et réessayez une fois.
2. Vérifiez que l'en-tête est bien `Authorization: Bearer <jeton>` et qu'il n'y a pas aussi d'en-tête `x-api-key`.
3. Demandez à l'administrateur du client de vérifier que l'utilisateur est actif et a accès à l'application **dans cet environnement**, avec un profil.

## L'API répond 403 Access denied

```json
{ "statusCode": 403, "message": "Access denied: token authorized party does not match the target application" }
```

**Cause** : le jeton a été émis pour une autre application que celle que vous appelez.

**Solution** : connectez l'utilisateur par l'hôte IAM de votre application. Un jeton n'est jamais réutilisable d'une application à l'autre.

## /api/me répond 404 ou 409

- `404` « Utilisateur non trouvé » : le compte Keycloak n'est rattaché à aucun utilisateur Wakastart. L'utilisateur doit être invité ou créé dans Wakastart avant de se connecter.
- `409` « Impossible de résoudre l'utilisateur de façon unique (customerId manquant ou invalide) » : l'adresse a des comptes chez plusieurs clients du même réseau et le jeton ne désigne pas le client. Reconnectez l'utilisateur en lui faisant choisir son organisation.

## L'enrichissement renvoie un objet vide

`POST /api/auth/enrich` répond `200` avec `{}`.

**Cause** : les mêmes que pour le `401` de `/api/me` : utilisateur inconnu, inactif ou sans accès à l'application dans cet environnement, ou jeton expiré.

**Solution** : appelez `GET /api/me` avec le même jeton ; son message d'erreur précise la situation. Traitez toujours l'absence de `token` comme un échec.

## Le rafraîchissement renvoie Token is not active

```json
{ "error": "invalid_grant", "error_description": "Token is not active" }
```

**Cause** : la session est terminée : 6 heures sans activité ou 12 heures au total par défaut, déconnexion, ou refresh token déjà remplacé par un rafraîchissement concurrent.

**Solution** : renvoyez l'utilisateur vers la connexion. Mutualisez les rafraîchissements et conservez toujours le dernier refresh token (voir [Rafraîchir la session](/v1.0/authentification/rafraichir-la-session)).

## L'utilisateur est reconnecté sans mot de passe après la déconnexion

**Cause** : seule la session locale a été supprimée ; la session Keycloak est restée ouverte.

**Solution** : appelez `POST /api/auth/logout` avec le refresh token avant de détruire la session (voir [Déconnecter un utilisateur](/v1.0/authentification/deconnecter-un-utilisateur)).

## L'utilisateur reste connecté quand la déconnexion échoue

Le bouton **Se déconnecter** ne fait rien, ou l'utilisateur reste sur la page après une erreur `4xx`, `5xx` ou réseau, ou une réponse `{ "success": false }`.

**Cause** : votre code ne supprime les cookies et le `sessionStorage` qu'en cas de succès de l'appel à `POST /api/auth/logout`.

**Solution** : supprimez les cookies dans un bloc `finally` de la route serveur, et videz le `sessionStorage` puis redirigez vers `/login` dans un bloc `finally` du bouton, quelle que soit la réponse.

**Pour vérifier** : coupez le réseau dans les outils du navigateur, cliquez sur **Se déconnecter** : vous arrivez sur `/login`, non connecté.

## Un build de dev connecte des comptes de production

Un testeur se connecte depuis votre build de dev, mais avec son compte de production, ou ne trouve pas son compte de dev.

**Cause** : le build envoie à Discovery le nom d'hôte de production, codé en dur ou lu dans une variable commune à tous les environnements. Discovery déduit l'environnement de ce nom d'hôte.

**Solution** : lisez le nom d'hôte dans `window.location`, ou dans l'en-tête `Host` de la requête reçue, et déclarez le nom d'hôte de dev comme hôte IAM de l'environnement dev.

**Pour vérifier** : la `keycloakUrl` renvoyée commence par `https://auth-dev.wakastart.app/`.

## Une réponse 429 Too Many Requests

**Cause** : la limite de débit par adresse IP de Discovery ou de l'API publique est atteinte. Le message est `ThrottlerException: Too Many Requests`.

**Solution** : n'appelez Discovery qu'une fois par tentative de connexion, ne relancez pas automatiquement après un `404`, et espacez les nouvelles tentatives de façon croissante.

## Toujours bloqué ?

Rassemblez ces informations avant de contacter le [support](/v1.0/support) :

- le nom d'hôte du front et l'environnement concerné ;
- l'heure exacte de l'essai, avec le fuseau ;
- la requête envoyée (sans jeton ni mot de passe) et la réponse complète, statut et corps ;
- l'adresse e-mail du compte de test, transmise par le canal du support uniquement.
