# Adapter votre application aux fiches par environnement

> Le WID d'un utilisateur présent sur plusieurs environnements change. Retrouvez vos utilisateurs par sub ou e-mail, et retirez les paramètres d'environnement.

Chaque environnement de votre application (dev, staging, prod) a désormais son propre référentiel d'utilisateurs. Une personne présente sur plusieurs environnements a une fiche, donc un WID, par environnement. Ce guide vous aide à adapter votre application **avant la bascule** : retrouver vos utilisateurs sans dépendre d'un WID, et cesser d'envoyer un environnement à l'API.

## Ce qui change

Jusqu'ici, une personne n'avait qu'une fiche, partagée entre les environnements de l'application. Désormais, une adresse présente en dev, en staging et en prod correspond à trois fiches indépendantes : désactiver, renommer ou supprimer l'une ne touche pas les autres. Le modèle est décrit dans [Comptes et environnements](/v1.0/utilisateurs/comptes-et-environnements).

À la bascule, la fiche unique d'une personne présente sur plusieurs environnements est éclatée :

| Fiche | `id` et `wid` |
|---|---|
| Celle de l'environnement le plus haut réellement déployé pour l'application : `prod`, sinon `staging`, sinon `dev` | **Conserve** l'ancien `id` et l'ancien WID |
| Chacune des autres | Reçoit un **nouvel** `id` et un **nouveau** WID |

Par exemple, une personne présente en prod et en dev garde son WID en prod et reçoit un nouveau WID en dev. Si l'application n'est déployée qu'en staging et en dev, c'est la fiche de staging qui garde l'ancien WID.

L'ancien WID n'est ni redirigé ni traduit : présenté depuis un autre environnement que celui de la fiche qui l'a gardé, il ne désigne plus aucune fiche et l'API répond `404`. Une personne qui n'existait que dans un environnement ne voit aucun changement.

### Ce qui ne change pas

| Donnée | Après la bascule |
|---|---|
| `sub` du jeton Keycloak de la personne dans un environnement | Inchangé |
| Adresse e-mail | Inchangée ; elle n'est plus unique que par client et par environnement |
| Profils attribués et droits dans cet environnement | Inchangés |
| WID des profils, des clients, des réseaux et des applications | Inchangés |
| WID de la fiche de l'environnement le plus haut déployé | Inchangé |

`keycloakId`, renvoyé par les endpoints de contrôle de jeton (`/api/token/*`), désigne désormais le compte Keycloak de l'environnement de la session ; il valait auparavant le compte de production, même en session dev. Il est donc égal au `sub` du jeton dans tous les environnements.

## Avant de commencer

- Repérez dans votre base les endroits où vous stockez le WID ou l'`id` d'un utilisateur Wakastart pour le retrouver plus tard. Ce sont eux qui cessent de fonctionner dans un environnement où la personne reçoit un nouveau WID.
- Repérez les appels à l'API publique qui envoient `env`, `envType` ou `envs`.

## Choisir une méthode de rattachement

Choisissez l'une des trois méthodes et déployez-la dans chaque environnement **avant** la bascule.

::::steps
### Rattacher vos utilisateurs au `sub` (recommandé)

Le `sub` du jeton identifie le compte Keycloak de la personne dans l'environnement de la session, et il ne change pas. Utilisez-le comme clé de rattachement :

```ts
import { decodeJwt } from "jose";

// À chaque connexion : retrouver l'utilisateur local par son sub, jamais par son WID
const claims = decodeJwt(enrichedToken);
const localUser = await db.user.upsert({
  where: { keycloakSub: claims.sub as string },
  update: { email: claims.email as string },
  create: { keycloakSub: claims.sub as string, email: claims.email as string },
});
```

Résultat : vos utilisateurs locaux sont retrouvés quel que soit le WID de leur fiche.

### Ou retrouver l'utilisateur par e-mail

Depuis votre serveur, la recherche par e-mail renvoie la fiche de l'environnement de l'appelant :

::endpoint{method="GET" path="/api/config/users/search"}

```bash
curl "https://api.wakastart.app/api/config/users/search?email=alice@exemple.fr" \
  -H "x-api-key: sk_test_exemple"
```

```ts
const response = await fetch(
  `https://api.wakastart.app/api/config/users/search?email=${encodeURIComponent("alice@exemple.fr")}`,
  { headers: { "x-api-key": process.env.WAKASTART_API_KEY! } },
);
const { items } = await response.json();
```

Réponse attendue :

```json
{ "items": [{ "wid": "Ab12Cd", "email": "alice@exemple.fr", "envType": "dev" }] }
```

La recherche porte sur l'adresse exacte, sans tenir compte de la casse, dans votre périmètre et dans l'environnement de la clé ou du jeton. N'envoyez que `email`.

### Ou rafraîchir le WID à chaque connexion

Si votre modèle impose de stocker le WID, relisez-le dans `/api/me` à chaque connexion et mettez à jour votre copie, en retrouvant votre utilisateur local par `sub` ou par e-mail :

```ts
const me = await fetch("https://api.wakastart.app/api/me", {
  headers: { Authorization: `Bearer ${accessToken}`, "x-enriched-token": enrichedToken },
}).then((r) => r.json());

if (localUser.wakastartWid !== me.wid) {
  await db.user.update({ where: { id: localUser.id }, data: { wakastartWid: me.wid } });
}
```

Résultat : le WID stocké est toujours celui de la fiche de l'environnement courant.
::::

## Retirer les paramètres d'environnement

L'environnement est désormais déduit de l'appelant : claim `wenv` du jeton, environnement de la clé API, ou hôte appelé pour Discovery. Vérifiez chacun de ces points dans votre code :

1. Retirez `env`, `envType` et `envs` de vos appels à l'API publique : ils sont refusés en `400` avec le message `Environment is deduced from the caller and cannot be provided`. Sont concernés la création d'un utilisateur (`envs`), la liste des utilisateurs (`envType`), les invitations (`envType`) et les droits d'un profil (`env`, `envType`).
2. Utilisez une clé API par environnement : les droits d'une clé se lisent dans la matrice profils × droits de l'environnement de la clé. Une clé de dev ou de staging peut gagner ou perdre des droits par rapport à avant, où la matrice de production s'appliquait. Une clé sans environnement est refusée (`403`).
3. Un jeton dont l'environnement ne peut pas être déduit est refusé (`401`) : il n'y a plus de repli sur la production.
4. Désignez un profil par son WID, sur les routes de profils comme dans les invitations (`profileWid`).
5. Envoyez à Discovery le hostname de la page dans chaque build : `host` sur `start-login`, `domain` sur la recherche par e-mail. Un build de dev qui envoie le hostname de production s'authentifie sur les fiches de production. Voir [Discovery](/v1.0/concepts/discovery).

## Vérifier le résultat

- Dans chaque environnement, un utilisateur qui existe aussi ailleurs se connecte et retrouve ses données dans votre application.
- Aucun de vos appels ne reçoit de `400` `Environment is deduced from the caller and cannot be provided`.
- `GET /api/me` renvoie, dans chaque environnement, le `wid` de la fiche de cet environnement, et votre application retrouve le même utilisateur local.

## Voir aussi

- [Comptes et environnements](/v1.0/utilisateurs/comptes-et-environnements)
- [Une fiche utilisateur par environnement (note de version)](/v1.0/notes-de-version/2026-10-29-une-fiche-utilisateur-par-environnement)
- [Charger le contexte utilisateur](/v1.0/authentification/charger-le-contexte-utilisateur)
- [Lister les utilisateurs](/v1.0/utilisateurs/lister-les-utilisateurs)
