Sessions et tokens

Chaque requête vers l'API de la plateforme est authentifiée en tant qu'utilisateur au sein d'un locataire. Cette page décrit précisément comment le serveur transforme une requête entrante en une identité et une portée locataire/site. Pour savoir comment obtenir un identifiant en premier lieu, voir Authentification.

Ordre de résolution des tokens

Le serveur vérifie les identifiants dans un ordre fixe et utilise le premier qui se résout :

  1. Authorization: Bearer <JWT> — le JWT est vérifié directement avec AUTH_SECRET (HS256). Il s'agit d'un pur contrôle de signature sans aller-retour vers la base de données, ce qui en fait le bon choix pour les scripts et les appels service-à-service.
  2. Cookie de session NextAuth — __Secure-authjs.session-token. C'est l'identifiant que porte déjà un navigateur connecté sur *.inklura.fr.
# Programmatique : JWT Bearer
curl "https://manage.inklura.fr/api/trpc/auth.getSession" \
  -H "Authorization: Bearer $INKLURA_TOKEN"

Le token Bearer et le cookie de session sont le même JWT HS256 — le cookie n'est que la manière dont un navigateur le stocke. Voir Authentification → JWT Bearer.

Portée locataire et site

L'authentification établit qui vous êtes ; une étape distincte établit dans quel locataire et quel site vous agissez.

Avec un JWT Bearer, la portée, c'est le token. Le token signé porte déjà tenantId et siteId, et le chemin Bearer les lit directement dans le token puis s'arrête — il ne consulte ni les en-têtes, ni les cookies, ni le Host. Un token émis pour le locataire X agit donc toujours en tant que locataire X, quel que soit l'hôte auquel vous l'envoyez. C'est le mécanisme derrière l'endpoint unique et multi-locataire de manage.inklura.fr : choisissez le locataire en choisissant le token.

Pour une requête par cookie de session (un navigateur connecté sans portée explicite), le serveur résout la portée à partir de, dans l'ordre :

  1. En-têtes — X-Tenant-Id et X-Site-Id.
  2. Cookies de sélection — selected_tenant, selected_site, selected_host.
  3. L'en-tête Host de la requête — utilisé en repli lorsque rien de plus explicite n'est présent.
X-Tenant-Id: <tenant uuid>
X-Site-Id:   <site uuid>

Les portails OpenAPI les annoncent sous les noms X-Tenant-ID / X-Site-ID, à côté du schéma bearerAuth. Le modèle locataire/site lui-même est décrit dans le Modèle de données.

Attention

Les X-Tenant-Id / X-Site-Id fournis par le client sont supprimés sur l'hôte partagé manage.inklura.fr à titre de mesure anti-usurpation ; vous ne pouvez donc pas y sélectionner un locataire avec ces en-têtes. Portez le locataire dans votre token Bearer (qui fait autorité sur tous les hôtes), ou ne fixez ces en-têtes que lorsque vous appelez le propre domaine d'un locataire.

Bypass réservé au développement

En développement, il existe un en-tête raccourci :

X-Auth-Bypass: true

Lorsqu'il est présent, le serveur génère une identité super-admin factice, ce qui vous permet d'exercer l'API sans véritable connexion.

Attention

X-Auth-Bypass est une commodité réservée au développement. Ne vous y fiez jamais face à manage.inklura.fr — les requêtes en production doivent présenter un vrai JWT Bearer ou un cookie de session.

Obtenir un token

Astuce

Une fois votre token obtenu, renseignez-le dans le panneau Identifiants & contexte de l'Explorateur d'API pour construire, copier et (si activé) envoyer de vraies requêtes.

Il n'y a pas de « création de clé API » en libre-service pour l'API complète — puisque le JWT est signé avec le AUTH_SECRET partagé, les tokens sont générés côté serveur par la plateforme. Réutilisez un token de session valide, ou mettez en place un identifiant de service. Le parcours complet (cookie de session, JWT Bearer, OIDC, lien magique) se trouve dans Authentification.

Les sous-systèmes de feed sont l'exception — ils utilisent leur propre FeedApiKey (feed_…) à portée limitée, plutôt qu'une session utilisateur. Voir Modèle de données → Clés API de feed et la note dans Authentification.