@ollaid/native-sso 2.8.1 → 2.8.3

package/docs/10_login-redirect.md

@@ -0,0 +1,103 @@
+# Login Redirect & Access Flow
+
+Version: `2.8.3`
+
+Ce document décrit le contrat à respecter pour éviter les deux régressions les plus fréquentes:
+
+- rester bloqué sur la page SSO après une connexion réussie
+- afficher une connexion réussie alors que l'utilisateur n'a pas encore d'accès à l'application SaaS
+
+## 1) Redirection après connexion
+
+La page autonome `NativeSSOPage` doit être utilisée avec un `redirectAfterLogin` lorsque vous voulez renvoyer automatiquement l'utilisateur vers une page de votre SaaS après authentification.
+
+Exemple:
+
+```tsx
+<NativeSSOPage
+  saasApiUrl="https://your-saas.com/api"
+  iamApiUrl="https://identityam.ollaid.com/api"
+  redirectAfterLogin="https://your-saas.com/app"
+  redirectAfterLogout="https://your-saas.com/"
+/>
+```
+
+Règle d'intégration:
+
+- si `redirectAfterLogin` est fourni, la page SSO doit rediriger automatiquement dès qu'une session valide existe
+- si `redirectAfterLogin` n'est pas fourni, la page peut rester sur l'écran SSO avec le bouton `Déconnexion`
+- `onLoginSuccess` sert au callback métier du frontend, mais ne remplace pas la redirection
+
+Comportement attendu côté page:
+
+- connexion réussie -> callback `onLoginSuccess` puis redirection vers `redirectAfterLogin`
+- session déjà valide au chargement -> redirection automatique vers `redirectAfterLogin`
+- déconnexion -> redirection vers `redirectAfterLogout` si ce paramètre est fourni
+
+## 2) Contrôle d'accès par application
+
+Le fait d'avoir un compte IAM ne signifie pas automatiquement que l'utilisateur a accès à chaque SaaS.
+
+Flux attendu:
+
+1. l'utilisateur saisit son email ou son téléphone
+2. il passe l'authentification IAM
+3. le backend vérifie s'il possède déjà un `AppAccess` pour cette application
+4. si oui, il renvoie une connexion normale
+5. si non, il renvoie `needs_access`
+6. le package affiche alors le modal de confirmation d'accès
+7. l'utilisateur confirme
+8. seulement à ce moment-là la connexion peut être finalisée
+
+Réponse attendue quand l'accès n'existe pas encore:
+
+```json
+{
+  "success": true,
+  "needs_access": true,
+  "process_token": "pst_xxx",
+  "application": {
+    "id": 12,
+    "name": "Mon SaaS",
+    "logo": "https://..."
+  },
+  "user": {
+    "id": 42,
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+}
+```
+
+Règles backend:
+
+- `needs_access` est le comportement par défaut quand l'accès à l'application n'existe pas encore
+- `BYPASS=true` sur le SaaS permet au backend d'auto-créer l'accès et de finaliser la connexion sans afficher le modal
+- le backend ne doit pas renvoyer une connexion finale tant que l'accès application n'a pas été validé, sauf si `BYPASS=true`
+
+Règles frontend:
+
+- si `needs_access` est reçu, afficher le modal de confirmation
+- ne pas appeler le callback de redirection finale avant la confirmation
+- ne pas marquer l'application comme connectée tant que `grantAccess()` n'a pas terminé
+
+## 3) Symptôme classique à éviter
+
+Si l'utilisateur voit:
+
+- `Connexion réussie`
+- puis reste sur la page SSO avec `Déconnexion`
+
+alors l'intégration n'a probablement pas fourni `redirectAfterLogin`, ou bien le callback frontend ne redirige pas vers une route métier.
+
+Si l'utilisateur se connecte pour la première fois sur un SaaS où il n'a jamais eu d'accès, mais qu'il voit directement `Connexion réussie` sans modal `needs_access` alors que `BYPASS` est désactivé, le backend a probablement validé la session trop tôt.
+
+## 4) Contrat à respecter
+
+Le package peut gérer l'UI, mais l'intégrateur SaaS doit fournir:
+
+- `redirectAfterLogin`
+- `redirectAfterLogout` si nécessaire
+- un backend qui renvoie `needs_access` quand l'accès à l'application n'existe pas encore, sauf si `BYPASS=true`
+
+Pour le détail du format des réponses backend, voir [Backend Contract](./2_backend-contract.md).

package/docs/11_session-refresh-resilience.md

@@ -0,0 +1,130 @@
+# Session Refresh & Resilience
+
+Version: `2.8.3`
+
+Ce document décrit le contrat de refresh token, la persistance des sessions et la stratégie de résilience attendue pour éviter toute déconnexion inutile en cas de réseau instable ou d'erreur transitoire.
+
+## Objectif
+
+Le but est simple:
+
+- ne pas perdre une session valide à cause d'une coupure réseau temporaire
+- ne pas déconnecter un utilisateur si le backend est indisponible quelques secondes
+- ne considérer une session comme invalide que sur une réponse explicite du backend
+
+## Contrat de session
+
+Une session Native SSO peut contenir:
+
+- `token` ou `auth_token`
+- `expires_at`
+- `refresh_token`
+- `refresh_expires_at`
+- `app_access_token_ref`
+- `user`
+
+Le package doit persister ces valeurs quand elles sont présentes.
+
+## Contrat du refresh token
+
+Le refresh token n'est pas un simple cache local. Il doit être traité comme une référence de session côté SaaS.
+
+Le backend SaaS doit:
+
+- créer un `refresh_token` au moment de l'exchange
+- persister son hash dans `personal_access_tokens.refresh_token_hash`
+- persister sa date d'expiration dans `personal_access_tokens.refresh_expires_at`
+- retourner le nouveau `refresh_token` à chaque rotation
+
+Le package doit:
+
+- stocker `refresh_token` et `refresh_expires_at` quand la réponse les fournit
+- utiliser `POST /api/native/refresh` seulement si `refresh_token` existe
+- remplacer le refresh token local si le backend le rote
+
+## Résultat attendu au refresh
+
+Le backend peut répondre:
+
+```json
+{
+  "success": true,
+  "expires_at": "2026-06-07T12:00:00+00:00",
+  "refresh_token": "rt_new_xxx",
+  "refresh_expires_at": "2026-08-07T12:00:00+00:00",
+  "app_access_token_ref": "aat_ref_xxx",
+  "user": {
+    "id": 42,
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+}
+```
+
+Dans ce cas:
+
+- la session reste active
+- le package met à jour le token local si nécessaire
+- le refresh token local est remplacé par le nouveau
+
+## Réponses d'erreur
+
+### `invalid_refresh`
+
+Cela signifie:
+
+- le refresh token ne correspond à aucune session connue
+- ou il a expiré
+- ou le hash stocké en base n'a jamais été persisté
+- ou le backend a déjà rotaté le refresh token et le client utilise une ancienne valeur
+
+Ce cas doit être traité comme une fin de session réelle.
+
+### Erreur réseau / timeout / 5xx
+
+Cela ne doit **pas** déconnecter immédiatement l'utilisateur.
+
+Le bon comportement est:
+
+- conserver la session locale
+- garder le token actuel
+- réessayer plus tard
+- ne déconnecter que si le backend renvoie explicitement un échec définitif
+
+## Règle de résilience
+
+Le package doit différencier:
+
+- **échec transitoire**: réseau, timeout, 502, 503, 504
+- **échec définitif**: `invalid_refresh`, `session_expired_idle`, token révoqué, réponse `401` explicite
+
+Un échec transitoire ne doit pas vider le storage de session.
+
+## Recommandation côté frontend hôte
+
+- ne pas appeler `logout()` automatiquement sur une simple erreur réseau
+- ne pas supprimer le storage si `refresh()` échoue sur timeout
+- afficher un état hors ligne ou un avertissement, mais garder l'utilisateur connecté
+- ne forcer la déconnexion qu'après plusieurs échecs définitifs consécutifs ou une réponse `401` claire
+
+## Recommandation côté backend SaaS
+
+- persister `refresh_token_hash` au moment de l'exchange
+- mettre à jour `refresh_expires_at` à chaque rotation
+- ne pas réutiliser un ancien refresh token après rotation
+- renvoyer toujours le nouveau `refresh_token` si une rotation est faite
+
+## Dépannage
+
+Si vous voyez `Refresh token invalide ou expiré`:
+
+- vérifiez que la table `personal_access_tokens` contient bien `refresh_token_hash`
+- vérifiez que le hash correspond au `refresh_token` stocké côté package
+- vérifiez que `refresh_expires_at` est encore valide
+- vérifiez que le frontend n'utilise pas un token d'une ancienne session
+
+Si vous voyez des déconnexions pendant une panne réseau:
+
+- vérifiez que votre code n'efface pas la session sur un simple timeout
+- vérifiez que votre logique de refresh ne confond pas `network error` et `invalid_refresh`
+

package/docs/12_login_mode.md

@@ -0,0 +1,55 @@
+# Needs Access & Bypass
+
+Version: `2.8.3`
+
+Ce document décrit le comportement attendu quand un utilisateur est authentifié mais n'a pas encore d'accès à une application SaaS.
+
+## Règle par défaut
+
+Le comportement par défaut doit être `needs_access`.
+
+Cela signifie:
+
+- si l'utilisateur a bien terminé son authentification IAM mais ne possède pas encore d'accès à l'application ciblée, le backend doit renvoyer `needs_access`
+- le package affiche alors le modal de confirmation
+- la connexion n'est finalisée qu'après `grantAccess()`
+
+## `BYPASS=true`
+
+Le SaaS peut activer un mode de bypass via son `.env`:
+
+```env
+BYPASS=true
+```
+
+Dans ce cas:
+
+- si l'utilisateur n'a pas encore d'accès à l'application, le backend auto-crée cet accès
+- le modal `needs_access` n'est pas affiché
+- la connexion est finalisée immédiatement comme si l'utilisateur avait confirmé manuellement
+
+## Valeurs possibles
+
+- `BYPASS=true` -> auto-acceptation du flux `needs_access`
+- `BYPASS=false` -> modal `needs_access` obligatoire si l'accès manque
+- `BYPASS` absent -> comportement identique à `false`
+- `BYPASS=null` ou vide -> comportement identique à `false`
+
+## Ce que le frontend doit faire
+
+- si `needs_access` est reçu, afficher le modal de confirmation
+- si la connexion a déjà été finalisée, rediriger vers la page métier prévue
+- ne pas considérer l'utilisateur comme connecté tant que `grantAccess()` n'a pas terminé
+
+## Ce que le backend doit faire
+
+- vérifier si l'utilisateur a déjà un `AppAccess`
+- si oui, finaliser la connexion normalement
+- si non et `BYPASS` est désactivé, renvoyer `needs_access`
+- si non et `BYPASS=true`, créer l'accès et finaliser la connexion
+
+## Résumé
+
+- `needs_access` = comportement standard
+- `BYPASS=true` = auto-acceptation contrôlée par le SaaS
+- le flux natif ne doit plus dépendre d'un mode legacy pour le comportement courant

package/docs/13_must_have_working.md

@@ -0,0 +1,60 @@
+# Must Have Working
+
+Version: `2.8.3`
+
+Cette page sert de vérification finale. Si un de ces points manque, l'intégration Native SSO n'est pas considérée comme complète.
+
+## 1) Authentification de base
+
+- **Connexion email**: l'utilisateur peut se connecter avec son email IAM.
+- **Connexion téléphone**: l'utilisateur peut se connecter avec son numéro IAM.
+- **OTP**: le code de vérification fonctionne quand le flux OTP est utilisé.
+- **Mot de passe**: la validation du mot de passe IAM fonctionne sans bloquer sur un faux état d'accès.
+
+## 2) Accès application
+
+- **`needs_access`**: état renvoyé quand l'utilisateur est authentifié mais n'a pas encore d'accès à l'application SaaS.
+- **Modal d'accès**: l'application affiche la demande de confirmation quand `needs_access` est reçu.
+- **Création d'accès**: après validation manuelle, l'accès SaaS est créé et la connexion se termine.
+- **`BYPASS=true`**: le SaaS peut auto-valider l'accès manquant et finaliser la connexion sans afficher le modal.
+
+## 3) Redirection
+
+- **`redirectAfterLogin`**: la page SSO redirige automatiquement après connexion réussie.
+- **`redirectAfterLogout`**: la page SSO redirige vers la page prévue après déconnexion.
+- **Pas de page bloquée**: l'utilisateur ne doit pas rester sur la page SSO avec `Déconnexion` après une connexion réussie.
+
+## 4) Session et refresh
+
+- **Refresh token**: la session peut être prolongée sans déconnexion inutile.
+- **Résilience réseau**: une erreur réseau ne doit pas supprimer une session valide.
+- **`invalid_refresh`**: ce statut signifie une vraie invalidation du refresh token, pas un simple timeout réseau.
+
+## 5) Sécurité et cohérence
+
+- **Clés application**: `app_key` et `secret_key` doivent correspondre à l'application ciblée.
+- **`encrypted_credentials`**: le blob chiffré doit suivre le contrat documenté dans `backend-contract.md`.
+- **Signature HMAC**: si l'intégration l'utilise, la signature doit être valide pour les requêtes signées.
+
+## 6) Profil SSO
+
+- **Onboarding profil**: les infos profil manquantes peuvent être complétées via la modal dédiée.
+- **Synchronisation profil**: les changements de profil doivent remonter correctement entre IAM et SaaS.
+
+## 7) Règle de validation finale
+
+Une intégration est considérée comme prête si:
+
+1. la connexion se fait
+2. `needs_access` apparaît quand il manque un accès
+3. `BYPASS=true` fonctionne quand il est activé
+4. la redirection se fait vers la page métier attendue
+5. la session survit aux erreurs réseau
+6. les infos profil liées au SSO sont cohérentes
+
+## Résumé
+
+- si le flux `needs_access` marche, la partie contrôle d'accès est bonne
+- si `BYPASS=true` fonctionne, le SaaS peut automatiser l'onboarding d'accès
+- si la session survit au réseau, le refresh token est correctement géré
+- si la redirection est propre, l'expérience utilisateur est complète

package/docs/14_backend_env_key.md

@@ -0,0 +1,50 @@
+# Backend Env Key
+
+Version: `2.8.3`
+
+Ce document liste les variables d'environnement backend nécessaires pour faire fonctionner le flux Native SSO.
+
+## Exemple de configuration
+
+```env
+# ==============================================================================
+# IAM SSO CONFIGURATION
+# ==============================================================================
+IAM_API_URL=https://identityam.ollaid.com/api
+IAM_AUTH_URL=https://iam.ollaid.com
+
+IAM_APP_KEY=oiam_ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+IAM_PUBLIC_KEY=oiam_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+IAM_SECRET_KEY=oiam_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+IAM_WEBHOOK_SECRET=oiam_whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+IAM_DEBUG=false
+BYPASS=false
+
+# ==============================================================================
+# END IAM SSO CONFIGURATION
+# ==============================================================================
+```
+
+## Rôle des variables
+
+- `IAM_API_URL`: URL API du backend IAM
+- `IAM_AUTH_URL`: URL d'authentification IAM utilisée par le backend ou les redirections
+- `IAM_APP_KEY`: clé publique d'application utilisée pour identifier le SaaS
+- `IAM_PUBLIC_KEY`: clé publique de chiffrement / vérification selon votre implémentation
+- `IAM_SECRET_KEY`: clé secrète utilisée pour les signatures et validations serveur
+- `IAM_WEBHOOK_SECRET`: secret utilisé pour signer les webhooks
+- `IAM_DEBUG`: active ou désactive les logs de debug IAM
+- `BYPASS`: active l'auto-acceptation du flux `needs_access` quand il vaut `true`
+
+## Règles
+
+- ne jamais committer les vraies clés dans la documentation
+- utiliser les vraies valeurs uniquement dans le `.env` du projet consommateur
+- `BYPASS=false` ou absent conserve le modal `needs_access`
+- `BYPASS=true` auto-crée l'accès quand il manque
+
+## Résumé
+
+- ce fichier sert de modèle
+- les valeurs sensibles doivent rester privées
+- `BYPASS` est la seule variable ici qui modifie directement le comportement du flux d'accès

package/docs/1_quick-start.md

@@ -0,0 +1,87 @@
+# Quick Start
+
+Version: `2.8.3`
+
+## Installation
+
+```bash
+npm install @ollaid/native-sso
+```
+
+## Route de test
+
+```tsx
+import { NativeSSOPage } from '@ollaid/native-sso';
+
+<Route
+  path="/auth/native-sso"
+  element={
+    <NativeSSOPage
+      saasApiUrl="https://your-saas.com/api"
+      iamApiUrl="https://identityam.ollaid.com/api"
+      homeUrl="https://your-saas.com/"
+      onLoginSuccess={(token, user) => {
+        console.log(token, user);
+      }}
+    />
+  }
+/>
+```
+
+`homeUrl` est optionnel. S'il est fourni, le package affiche un lien "Retourner à l'accueil" sur les écrans racine de connexion et d'inscription. Sans valeur, le lien reste caché.
+
+Si vous utilisez `NativeSSOPage`, fournissez aussi `redirectAfterLogin` pour éviter de rester sur la page SSO après une connexion réussie:
+
+```tsx
+<NativeSSOPage
+  saasApiUrl="https://your-saas.com/api"
+  iamApiUrl="https://identityam.ollaid.com/api"
+  redirectAfterLogin="https://your-saas.com/app"
+/>
+```
+
+Sans `redirectAfterLogin`, la page peut rester affichée avec le bouton `Déconnexion`, ce qui est normal pour un usage purement autonome.
+
+## Côté frontend SaaS
+
+```ts
+import { getSsoSessionSnapshot, logout } from '@ollaid/native-sso';
+
+const session = getSsoSessionSnapshot();
+
+if (session.authToken) {
+  console.log(session.user);
+}
+```
+
+### Forme du snapshot
+
+```ts
+{
+  authToken: string | null;
+  refreshToken: string | null;
+  refreshExpiresAt: string | null;
+  tokenExpiresAt: string | null;
+  appAccessTokenRef: string | null;
+  aliasReference: string | null;
+  accountType: string | null;
+  deviceId: string | null;
+  sessionUuid: string | null;
+  user: unknown | null;
+}
+```
+
+### Déconnexion
+
+```ts
+const result = await logout();
+// { success: true }
+```
+
+## Règles simples
+
+- N’accédez pas au storage directement.
+- Utilisez `getSsoSessionSnapshot()` pour lire la session.
+- Utilisez `logout()` pour déconnecter.
+- `clearAuthToken()` reste seulement pour compatibilité.
+- Si vous êtes sur Capacitor, fournissez un `storage` natif si possible.

package/docs/2_backend-contract.md

@@ -0,0 +1,199 @@
+# Backend Contract
+
+Version: `2.8.3`
+
+## Endpoints SaaS requis
+
+- `GET /api/native/config`
+- `POST /api/native/exchange`
+- `POST /api/native/check-token`
+- `POST /api/native/refresh`
+- `POST /api/native/logout`
+- `POST /api/native/password-link` pour le flux de redirection mot de passe
+
+## Exemple rapide
+
+### 1) `GET /api/native/config`
+
+Réponse:
+
+```json
+{
+  "success": true,
+  "app_key": "oiam_ak_xxx",
+  "encrypted_credentials": "base64(IV::ciphertext_base64)...",
+  "iam_api_url": "https://identityam.ollaid.com/api",
+  "credentials_ttl": 300,
+  "debug": false
+}
+```
+
+Format attendu pour `encrypted_credentials`:
+
+- chiffrement `AES-256-CBC`
+- IV aléatoire de 16 octets
+- clé dérivée avec `hash('sha256', secret_key, true)`
+- sérialisation finale: `base64(IV::ciphertext_base64)`
+- contenu chiffré: un JSON avec au minimum `app_key` et `secret_key`
+
+### 2) `POST /api/native/exchange`
+
+Body:
+
+```json
+{
+  "callback_token": "cbk_xxx"
+}
+```
+
+Réponse:
+
+```json
+{
+  "success": true,
+  "token": "1|sanctum_token",
+  "expires_at": "2026-05-15T17:00:00+00:00",
+  "refresh_token": "ref_xxx",
+  "refresh_expires_at": "2026-06-15T17:00:00+00:00",
+  "app_access_token_ref": "aat_ref_xxx",
+  "user": {
+    "reference": "USR-XXXX",
+    "name": "John Doe",
+    "email": "john@example.com",
+    "alias_reference": "ALI-XXXX"
+  },
+  "user_infos": {
+    "name": "John Doe",
+    "email": "john@example.com",
+    "ccphone": "+221",
+    "phone": "771234567",
+    "address": "Rue 10, Plateau",
+    "town": "Dakar",
+    "country": "SN"
+  }
+}
+```
+
+### 2 bis) Flux `needs_access` sur une nouvelle application
+
+Quand l'utilisateur est bien authentifié côté IAM mais qu'il n'a encore aucun accès sur l'application SaaS ciblée, le backend doit renvoyer un état `needs_access`.
+
+Réponse attendue:
+
+```json
+{
+  "success": true,
+  "needs_access": true,
+  "process_token": "pst_xxx",
+  "application": {
+    "id": 12,
+    "name": "Mon SaaS",
+    "logo": "https://..."
+  },
+  "user": {
+    "id": 42,
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+}
+```
+
+Comportement du package:
+
+- il affiche l'écran de confirmation "Confirmer la création de mon compte"
+- il garde le `process_token` pour finaliser l'attribution d'accès
+- il ne termine pas la connexion tant que l'utilisateur n'a pas confirmé
+
+Cas de configuration backend:
+
+- `BYPASS=true` sur le SaaS -> le backend auto-crée l'accès et finalise la connexion comme si le modal avait été validé
+- `BYPASS` absent, `false` ou vide -> le backend renvoie `needs_access` dès que l'accès n'existe pas encore
+
+Le flux natif ne dépend plus du mode legacy d'autorisation pour le comportement standard. Le contrat natif doit être centré sur `needs_access` par défaut.
+
+### 3) `POST /api/native/check-token`
+
+Réponse `200` si le token est valide:
+
+```json
+{
+  "success": true,
+  "user": {
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+}
+```
+
+### 4) `POST /api/native/refresh`
+
+Le package tente ce refresh si `refresh_token` existe et que `check-token` renvoie `401`.
+
+### 5) `POST /api/native/logout`
+
+Réponse:
+
+```json
+{ "success": true }
+```
+
+### 6) `POST /api/native/password-link`
+
+Réponse recommandée:
+
+```json
+{
+  "success": true,
+  "redirect_url": "https://identityam.ollaid.com/auth/auto-connect?magic_token=xxx",
+  "magic_token": "xxx",
+  "expires_at": "2026-05-18T12:00:00+00:00"
+}
+```
+
+Le backend SaaS doit relayer l'appel vers IAM sur `POST /api/backoffice/auth/password-link`, puis renvoyer au package une URL de redirection prête à ouvrir.
+
+## Ce que le package envoie
+
+- `X-Device-Id`
+- `X-Session-UUID`
+- `X-Device-Name`
+- `X-Device-Model`
+- `X-Device-Manufacturer`
+- `X-Device-Operating-System`
+- `X-Device-Os-Version`
+- `X-Device-Platform`
+- `X-Device-Browser`
+- `X-Device-Language`
+- `X-Device-WebView-Version`
+- `X-Device-Is-Native`
+- `X-Device-Label`
+
+## Ce que le backend doit faire
+
+- Répondre en JSON.
+- Gérer `refresh_token` si disponible.
+- Retourner `refresh_token` / `refresh_expires_at` si vous activez le refresh.
+- Faire du `check-token` un signal de validité, avec tentative de refresh côté package après un `401`.
+- Révoquer de façon ciblée via `app_access_token_ref`.
+- Mettre à jour `last_active_at` si vous appliquez la politique d’activité.
+- Exposer les sessions sous forme multi-device sans tuer les autres appareils.
+- Renvoyer aussi les champs de profil utiles au package dans `user_infos` quand ils sont connus, notamment `name`, `email`, `ccphone`, `phone`, `address`, `town` et `country`.
+
+## Dépannage
+
+- `Identifiants application invalides` au moment du login natif signifie en pratique que `POST /api/iam/native/encrypt` n'a pas réussi à valider le couple `app_key` + `encrypted_credentials`.
+- `Déchiffrement échoué` côté IAM veut dire que `encrypted_credentials` ne correspond pas à la `secret_key` attendue par l'application, ou que la valeur envoyée est mal formée.
+- `Credentials expirés` veut dire que le blob de credentials reçu par le package est trop ancien par rapport au TTL configuré. Dans ce cas, le package doit refaire `GET /api/native/config`.
+- Si l'utilisateur est authentifié mais n'a pas encore accès à l'application, le bon signal est `needs_access`. Le package doit afficher la demande de confirmation d'accès, pas un simple échec de login.
+- Si ce flux n'apparaît plus, vérifiez que `BYPASS` n'est pas activé par erreur côté SaaS et que les endpoints IAM retournent bien `needs_access` après l'authentification.
+- Si vous avez copié des clés depuis une application déjà en production et que le login échoue quand même, vérifiez d'abord que `GET /api/native/config` renvoie bien les clés attendues pour cette application.
+- Vérifiez aussi que le SaaS ne sert pas un `encrypted_credentials` mis en cache avec une ancienne `secret_key`.
+- Vérifiez enfin que le format chiffré reste `base64(IV::ciphertext_base64)` comme attendu par le package.
+
+## APIs IAM Account
+
+Si votre intégration utilise aussi les synchronisations utilisateur server-to-server, consultez [IAM Account](./5_iam-account.md).
+
+## Session refresh et résilience
+
+Le contrat de `refresh_token`, la rotation, la persistance des sessions et la gestion des erreurs réseau sont détaillés dans [Session Refresh & Resilience](./11_session-refresh-resilience.md).