# Discovery

> Obtenir l'adresse de connexion Keycloak d'une wakapp à partir du nom d'hôte de son front, seul ou avec l'e-mail de l'utilisateur.

Discovery indique à votre application vers quel realm Keycloak envoyer un utilisateur. Votre application ne connaît jamais son realm : elle envoie à Discovery **le nom d'hôte de son propre front**, qui désigne à la fois l'application et l'environnement. L'environnement n'est jamais un paramètre : Discovery le déduit de l'[hôte IAM](/v1.0/glossaire#hôte-iam) qui porte ce nom d'hôte, et ne cherche que dans les fiches utilisateurs de cet environnement. Le service est public et s'appelle sans jeton, puisque l'utilisateur n'est pas encore connecté.

**URL de base** : `https://discovery.wakastart.app`

L'instance Keycloak, elle, dépend de l'environnement : elle est lue dans la `keycloakUrl` renvoyée par Discovery, ou dans la variable `KEYCLOAK_URL` de votre application, posée par environnement. Le fonctionnement est expliqué dans [Discovery](/v1.0/concepts/discovery).

## Choisir le bon endpoint

| Votre cas | Endpoint | Ce que votre application envoie |
|---|---|---|
| Un nom d'hôte correspond à un seul client (cas le plus courant) | [`POST /discover/start-login`](#obtenir-ladresse-de-connexion-par-nom-dhôte) | Le nom d'hôte complet de la page, par exemple `mon-app.exemple.fr` |
| Plusieurs clients d'un même réseau partagent le nom d'hôte | [`POST /discover/start-login`](#départager-plusieurs-clients-par-e-mail) | Le nom d'hôte complet et l'e-mail saisi |
| Un portail commun à plusieurs réseaux, ou un affichage avant connexion | [`GET /discover/email`](#retrouver-les-comptes-dun-e-mail-pour-votre-front) | L'e-mail saisi et le nom d'hôte du front dans `domain` |

## L'objet compte découvert

Renvoyé par `GET /discover/email`, un élément par compte trouvé.

| Champ | Type | Description |
|---|---|---|
| `user_email` | chaîne | E-mail du compte |
| `customer_wid`, `customer_name` | chaîne | Identifiant court et nom du [client](/v1.0/glossaire#client) du compte |
| `customer_subdomain` | chaîne ou `null` | Sous-domaine du client |
| `network_wid`, `network_name` | chaîne | Identifiant court et nom du [réseau](/v1.0/glossaire#réseau) |
| `network_subdomain` | chaîne ou `null` | Sous-domaine du réseau |
| `network_realm_id` | chaîne ou `null` | Nom du [realm](/v1.0/glossaire#realm) Keycloak du réseau **dans l'environnement de l'hôte IAM** désigné par `domain`, à placer dans l'URL de connexion |
| `partner_wid`, `partner_name` | chaîne | Identifiant court et nom du [propriétaire](/v1.0/glossaire#propriétaire) de l'application |
| `idp_id`, `idp_name`, `idp_type` | chaîne ou `null` | Fournisseur d'identité SSO du client s'il en a un ; `idp_type` vaut `OIDC` ou `SAML` |
| `keycloak_org_alias` | chaîne ou `null` | Alias de l'organisation Keycloak du client, égal à son WID |
| `app_wid`, `app_name` | chaîne | Identifiant court et nom de l'application |
| `app_client_id` | chaîne | Identifiant du client Keycloak de l'application, à placer dans l'URL de connexion |
| `app_url_front` | chaîne ou `null` | URL du front de l'application |
| `theme_name`, `theme_css_path`, `theme_css_vars_light`, `theme_css_vars_dark` | chaîne, objet ou `null` | Thème applicable, résolu du client vers le réseau puis l'application |
| `branding_logo_light`, `branding_logo_dark`, `branding_bg_light` | chaîne ou `null` | Logo et fond de l'application. Les deux champs de logo portent la même image |
| `branding_favicon`, `branding_bg_dark` | `null` | Réservés, toujours `null` |
| `default_lang` | chaîne ou `null` | Langue par défaut de l'application |

## Obtenir l'adresse de connexion par nom d'hôte

::endpoint{method="POST" path="/discover/start-login"}

Public. Renvoie l'URL d'autorisation Keycloak complète, prête à suivre : instance, realm, client, adresse de retour et paramètres PKCE compris.

**Corps**

| Champ | Type | Obligatoire | Contraintes | Description |
|---|---|---|---|---|
| `host` | chaîne | oui | non vide, 253 caractères au plus | Nom d'hôte complet du front, sans schéma ni chemin, tel que le navigateur l'a demandé (`window.location.host`, ou en-tête `Host` de la requête reçue par votre serveur). Il désigne l'application, le réseau et l'environnement. `mon-app.exemple.fr` est résolu ; un fragment comme `mon-app` ne l'est pas |
| `email` | chaîne | non | e-mail valide, 254 caractères au plus | Adresse saisie par l'utilisateur, pour départager plusieurs clients du réseau désigné par `host`. Elle ne sert jamais à trouver le réseau |
| `customerWid` | chaîne | non | 6 caractères au plus | Client choisi par l'utilisateur parmi les candidats d'une réponse ambiguë. Inutile au premier appel |
| `redirectUri` | chaîne | oui | 2 048 caractères au plus | Adresse de retour après connexion, recopiée telle quelle dans l'URL. Elle doit être déclarée pour cet hôte, sinon Keycloak la refuse |
| `state` | chaîne | non | 256 caractères au plus | Valeur aléatoire contre la falsification de requête, à revérifier au retour |
| `nonce` | chaîne | non | 256 caractères au plus | Valeur OIDC contre le rejeu |
| `codeChallenge` | chaîne | non | 128 caractères au plus | Empreinte PKCE : `base64url(SHA-256(code_verifier))` |
| `codeChallengeMethod` | chaîne | non | `S256` uniquement | Méthode PKCE. Vaut `S256` si `codeChallenge` est fourni |

```bash
curl -s https://discovery.wakastart.app/discover/start-login \
  -H 'Content-Type: application/json' \
  -d '{
    "host": "mon-app.exemple.fr",
    "redirectUri": "https://mon-app.exemple.fr/api/auth/callback",
    "state": "q8XGm2Vt0oKc4bQ1",
    "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
    "codeChallengeMethod": "S256"
  }'
```

Appelez Discovery depuis le serveur de votre application : le service n'accepte pas les appels croisés d'un navigateur. Par exemple, dans la route `/login` de votre serveur :

```ts
// host : en-tête Host de la requête reçue, par exemple "mon-app.exemple.fr"
const response = await fetch("https://discovery.wakastart.app/discover/start-login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    host,
    redirectUri: `https://${host}/api/auth/callback`,
    state,
    codeChallenge,
    codeChallengeMethod: "S256",
  }),
});
if (response.status === 404) throw new Error("Hôte inconnu de Discovery");
const { keycloakUrl } = (await response.json()) as { keycloakUrl: string };
// redirigez ensuite le navigateur vers keycloakUrl (statut 302)
```

**Réponse `200`**

```json
{
  "keycloakUrl": "https://auth.wakastart.app/realms/realm-EXNET1/protocol/openid-connect/auth?client_id=EXAPP1&response_type=code&scope=openid+profile+email+organization&redirect_uri=https%3A%2F%2Fmon-app.exemple.fr%2Fapi%2Fauth%2Fcallback&state=q8XGm2Vt0oKc4bQ1&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256"
}
```

L'origine de l'URL désigne l'instance Keycloak de l'environnement auquel l'hôte est rattaché. Le chemin porte le realm, le paramètre `client_id` l'identifiant de votre application : conservez-les pour échanger le code contre des jetons à l'adresse `<origine>/realms/<realm>/protocol/openid-connect/token`.

Le scope demandé est toujours `openid profile email organization` : le scope `organization` permet à l'utilisateur de choisir son organisation dans Keycloak s'il en a plusieurs.

Un ancien sous-domaine de réseau ou de client (`reseau-exemple`) reste accepté dans `host`, en repli. Comme il ne désigne aucun environnement, Discovery le déduit des hôtes IAM actifs du réseau ou du client, et ne le résout que s'ils appartiennent tous au même environnement. Préférez toujours le nom d'hôte complet.

**Erreurs**

| Statut | Message | Cause |
|---|---|---|
| `400` | `invalid_request: host is required (non-empty string, max 253 chars)` | `host` absent ou vide. Un appel avec l'e-mail seul n'est plus accepté |
| `400` | Tableau de messages de validation | Autre champ absent, inconnu ou hors contrainte |
| `404` | `not_found` | Aucun hôte IAM actif ne correspond au nom d'hôte ; sous-domaine de repli dont les hôtes IAM actifs couvrent plusieurs environnements, ou qui n'en a aucun ; realm de l'environnement dev ou staging pas encore créé pour le réseau ; `customerWid` qui ne fait pas partie des candidats. La réponse prend toujours le même temps |
| `429` | `ThrottlerException: Too Many Requests` | Limite de débit atteinte |

### Départager plusieurs clients par e-mail

Même endpoint, `POST /discover/start-login`, avec `email` en plus de `host`. Utilisez-le quand un même nom d'hôte sert plusieurs clients d'un réseau : une adresse peut alors avoir une fiche chez plusieurs d'entre eux. Le nom d'hôte reste obligatoire et désigne toujours le réseau, l'application et l'environnement.

```bash
curl -s https://discovery.wakastart.app/discover/start-login \
  -H 'Content-Type: application/json' \
  -d '{
    "host": "rdv.groupe-exemple.fr",
    "email": "alice@clinique-exemple.fr",
    "redirectUri": "https://rdv.groupe-exemple.fr/api/auth/callback",
    "state": "q8XGm2Vt0oKc4bQ1",
    "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
    "codeChallengeMethod": "S256"
  }'
```

Si l'adresse correspond à un seul client, ou à aucun, la réponse est la `keycloakUrl` habituelle. Si elle correspond à plusieurs clients, la réponse `200` liste les candidats :

```json
{
  "ambiguous": true,
  "candidates": [
    { "customer_wid": "EXCLI1", "customer_name": "Clinique Exemple", "customer_subdomain": null },
    { "customer_wid": "EXCLI2", "customer_name": "Centre Exemple", "customer_subdomain": "centre-exemple" }
  ]
}
```

Présentez la liste à l'utilisateur, puis rappelez `start-login` avec les mêmes champs et le `customerWid` choisi. Un `customerWid` qui ne figure pas parmi les candidats de cette adresse répond `404`.

```ts
const body = { host, email, redirectUri, state, codeChallenge, codeChallengeMethod: "S256" };
let result = await startLogin(body); // POST /discover/start-login
if ("ambiguous" in result) {
  const customerWid = await askUserToChoose(result.candidates); // votre écran de choix
  result = await startLogin({ ...body, customerWid });
}
// redirigez ensuite le navigateur vers result.keycloakUrl
```

## Retrouver les comptes d'un e-mail pour votre front

::endpoint{method="GET" path="/discover/email"}

Public. Renvoie les comptes rattachés à une adresse e-mail, **limités à l'application dont le front porte le nom d'hôte `domain`**. Votre application assemble ensuite elle-même l'URL de connexion.

**Paramètres de requête**

| Paramètre | Type | Obligatoire | Contraintes | Description |
|---|---|---|---|---|
| `email` | chaîne | oui | E-mail valide, 254 caractères au plus | Adresse saisie par l'utilisateur |
| `domain` | chaîne | à envoyer toujours | 253 caractères au plus | Nom d'hôte du front de votre application (`window.location.hostname`) |

Discovery cherche l'hôte IAM actif qui porte `domain`, sans tenir compte de la casse, du schéma `http(s)://`, du port ni du `/` final. Il en déduit l'application et l'environnement, ne renvoie que les comptes de cette application dans cet environnement, et place dans `network_realm_id` le realm de cet environnement. Un `domain` qui ne correspond à aucun hôte IAM de l'application renvoie `{ "users": [] }`, comme une adresse inconnue : Discovery ne se rabat jamais sur la production.

```bash
curl -s "https://discovery.wakastart.app/discover/email?email=alice%40clinique-exemple.fr&domain=mon-app.exemple.fr"
```

**Réponse `200`**

```json
{
  "users": [
    {
      "user_email": "alice@clinique-exemple.fr",
      "customer_wid": "EXCLI1",
      "customer_name": "Clinique Exemple",
      "customer_subdomain": null,
      "network_wid": "EXNET1",
      "network_name": "Réseau Exemple",
      "network_subdomain": "reseau-exemple",
      "network_realm_id": "realm-EXNET1",
      "partner_wid": "EXPRT1",
      "partner_name": "Éditeur Exemple",
      "idp_id": null,
      "idp_name": null,
      "idp_type": null,
      "keycloak_org_alias": "EXCLI1",
      "app_wid": "EXAPP1",
      "app_name": "Mon App",
      "app_client_id": "EXAPP1",
      "app_url_front": "https://mon-app.exemple.fr",
      "theme_name": null,
      "theme_css_path": null,
      "theme_css_vars_light": null,
      "theme_css_vars_dark": null,
      "branding_logo_light": null,
      "branding_logo_dark": null,
      "branding_favicon": null,
      "branding_bg_light": null,
      "branding_bg_dark": null,
      "default_lang": "fr"
    }
  ]
}
```

La forme de la réponse est la même, que l'adresse existe ou non : `{ "users": [] }` signifie qu'aucun compte ne correspond pour ce front. Affichez alors un message neutre, comme « Vérifiez votre adresse et réessayez », jamais « Cette adresse n'existe pas ».

Avec un compte, votre application construit l'URL de connexion à partir de sa variable `KEYCLOAK_URL` :

```ts
const [account] = users; // proposez un choix à l'utilisateur s'il y en a plusieurs
const authUrl = new URL(
  `${process.env.KEYCLOAK_URL}/realms/${account.network_realm_id}/protocol/openid-connect/auth`,
);
authUrl.search = new URLSearchParams({
  client_id: account.app_client_id,
  response_type: "code",
  scope: "openid profile email organization",
  redirect_uri: "https://mon-app.exemple.fr/api/auth/callback",
  state,
  code_challenge: codeChallenge,
  code_challenge_method: "S256",
}).toString();
```

:::important
**Envoyez `domain` dès maintenant.** Une recherche sans `domain` ne porte aujourd'hui que sur les fiches de production : vos builds de dev et de staging n'y trouvent aucun de leurs utilisateurs. À une date qui sera annoncée, elle sera refusée et renverra `{ "users": [] }` quelle que soit l'adresse. Vérifiez aussi que le nom d'hôte de chaque environnement est déclaré comme hôte IAM de l'application.
:::

**Erreurs**

| Statut | Message | Cause |
|---|---|---|
| `400` | `email must be an email` | Adresse absente ou mal formée |
| `429` | `ThrottlerException: Too Many Requests` | Limite de débit atteinte |

### Depuis l'API publique

::endpoint{method="GET" path="/api/discovery/email"}

L'API publique (`https://api.wakastart.app/api`) relaie la même recherche, sans jeton, avec les mêmes paramètres `email` et `domain` et la même réponse. `domain` peut y être un nom d'hôte ou une URL complète : l'API le ramène au nom d'hôte avant de le transmettre. Une valeur impossible à analyser répond `400` `domain must be a valid host name`. Cette route est limitée à 10 requêtes par minute.

```bash
curl -s "https://api.wakastart.app/api/discovery/email?email=alice%40clinique-exemple.fr&domain=https%3A%2F%2Fmon-app.exemple.fr"
```

## Lire la personnalisation d'un sous-domaine

::endpoint{method="GET" path="/discover/subdomain"}

Public. Renvoie le réseau ou le client qui porte un sous-domaine, avec son thème et ses visuels, pour habiller une page de connexion avant toute authentification.

| Paramètre | Type | Obligatoire | Contraintes |
|---|---|---|---|
| `subdomain` | chaîne | oui | 63 caractères au plus, lettres, chiffres et tirets, sans tiret en début ni en fin |

```bash
curl -s "https://discovery.wakastart.app/discover/subdomain?subdomain=reseau-exemple"
```

**Réponse `200`**

```json
{
  "subdomain": "reseau-exemple",
  "result": {
    "type": "network",
    "network_wid": "EXNET1",
    "network_name": "Réseau Exemple",
    "network_subdomain": "reseau-exemple",
    "network_realm_id": "realm-EXNET1",
    "partner_wid": "EXPRT1",
    "partner_name": "Éditeur Exemple",
    "customer_wid": null,
    "customer_name": null,
    "customer_subdomain": null,
    "app_wid": "EXAPP1",
    "app_name": "Mon App",
    "app_client_id": "EXAPP1",
    "app_url_front": "https://mon-app.exemple.fr",
    "theme_name": null,
    "theme_css_path": null,
    "theme_css_vars_light": null,
    "theme_css_vars_dark": null,
    "branding_logo_light": null,
    "branding_logo_dark": null,
    "branding_favicon": null,
    "branding_bg_light": null,
    "branding_bg_dark": null,
    "default_lang": "fr"
  }
}
```

`type` vaut `network` ou `customer`. Un sous-domaine ne porte pas d'environnement : Discovery le déduit des hôtes IAM actifs du réseau ou du client, et `network_realm_id` est le realm de cet environnement.

La réponse est `{ "subdomain": "…", "result": null }`, avec le statut `200`, dans chacun de ces cas :

- le sous-domaine est inconnu ;
- le réseau ou le client n'a aucun hôte IAM actif ;
- ses hôtes IAM actifs couvrent plusieurs environnements, par exemple dev et prod ;
- l'environnement déduit est dev ou staging, et le realm de cet environnement n'existe pas encore pour le réseau.

Discovery ne se rabat jamais sur le realm de production. Traitez `result: null` comme « contexte indisponible » : affichez la page de connexion générique et passez par `start-login` avec le nom d'hôte complet.

**Erreurs** : `400` `subdomain must contain only alphanumeric characters and hyphens`.

## Ce qu'il ne faut pas faire

- **N'envoyez jamais d'identifiant d'application** pour orienter la résolution : c'est l'URL de votre front qui désigne l'application. Votre application n'a pas à connaître son propre identifiant de client.
- **N'appelez jamais `POST /discover/start-login` sans `host`**, même avec un e-mail : la réponse est `400`. L'e-mail ne sert qu'à départager les clients du réseau désigné par le nom d'hôte.
- **N'envoyez pas le nom d'hôte d'un autre environnement** : un build de dev qui envoie le nom d'hôte de production connecte ses utilisateurs sur les fiches de production. Lisez-le dans `window.location`, sans le coder en dur.
- **N'envoyez pas un sous-domaine extrait** quand vous avez le nom d'hôte complet : c'est le nom d'hôte qui désigne l'environnement.
- **Ne codez pas d'URL Keycloak en dur** : lisez-la dans la réponse de Discovery ou dans `KEYCLOAK_URL`.
- **Ne réessayez pas automatiquement sur `404`** : la réponse ne changera pas tant que l'hôte n'est pas déclaré.

## Limites de débit

Discovery limite les requêtes par adresse IP, sur l'ensemble de ses endpoints :

| Fenêtre | Limite |
|---|---|
| 1 minute | 5 requêtes |
| 10 minutes | 20 requêtes |
| 1 heure | 100 requêtes |

Appelez `start-login` une seule fois par tentative de connexion. Ne journalisez pas les e-mails envoyés à Discovery : ce sont des données personnelles.
