Authentification

Chaque appel à l'API Inklura est authentifié en tant qu'utilisateur au sein d'un locataire. Il n'existe pas de « clé API d'organisation » distincte pour l'API générale — une requête porte une identité de session, et le serveur en déduit la portée locataire/site (plus, en option, des en-têtes de tenancy).

Astuce

Essayez de manière interactive. L'Explorateur d'API dispose d'un panneau Identifiants & contexte — collez votre token Bearer et (au besoin) vos X-Tenant-Id / X-Site-Id, et il génère un cURL prêt à l'emploi pour n'importe quel endpoint. Tout ce que vous saisissez reste dans votre navigateur (localStorage) et n'est jamais envoyé au site docs.

Les quatre manières de s'authentifier

Méthode À utiliser pour Comment
Cookie de session Applications navigateur sur *.inklura.fr __Secure-authjs.session-token défini à la connexion
JWT Bearer Scripts, serveurs, service-à-service Authorization: Bearer <jwt>
OIDC Connexion déléguée via l'IdP de la plateforme Authorization-code + PKCE auprès de auth.1clic.pro
Clé API de feed Feeds de contenu en lecture seule FeedApiKey (feed_…) — limitée à des fonctionnalités, débit plafonné

Cookie de session

Se connecter sur manage.inklura.fr génère un cookie de session JWT NextAuth (Auth.js) :

  • authjs.session-token en développement
  • __Secure-authjs.session-token en production

Le token est un JWT HS256 signé avec le AUTH_SECRET de la plateforme, valable 30 jours. Le même cookie est reconnu sur tous les sous-domaines *.inklura.fr — c'est ce qui fait fonctionner le SSO.

JWT Bearer (accès programmatique)

Pour tout ce qui n'est pas un navigateur — un script, un service backend, ou une application Inklura qui en appelle une autre — envoyez le JWT de session en tant que token Bearer :

curl https://manage.inklura.fr/api/trpc/auth.getSession \
  -H "Authorization: Bearer $INKLURA_TOKEN"

Le serveur vérifie le JWT directement avec AUTH_SECRET (aucun aller-retour vers la base de données, aucune portée de requête navigateur), puis résout votre locataire/site. C'est exactement ainsi que la console et les clients desktop s'authentifient auprès du serveur d'API allégé.

Note

Comme le JWT est signé avec le AUTH_SECRET partagé, les tokens ne peuvent être générés que côté serveur par la plateforme. Il n'y a pas de « création de clé API » en libre-service pour l'API complète. Pour automatiser, réutilisez un token de session valide, ou contactez support@inklura.fr pour mettre en place un identifiant de service.

OIDC (auth.1clic.pro)

Le fournisseur d'identité d'Inklura est un serveur OIDC dédié, à l'adresse auth.1clic.pro. La console utilise un flux authorization-code + PKCE (S256) :

  1. GET /api/auth/oidc-login → redirection vers auth.1clic.pro/oauth2/authorize
  2. L'utilisateur s'authentifie
  3. GET /api/auth/callback?code=… → le code est échangé contre des tokens (vérifiés via JWKS) et une session NextAuth est générée

L'identifiant client de la console est cm-nextjs-app. Si vous construisez une nouvelle application first-party censée participer à la connexion de la plateforme, vous enregistrez un client auprès de l'IdP — voir Authentification unique.

Onboarding par lien magique

Les administrateurs invitent les utilisateurs avec un lien signé et à usage unique, plutôt qu'avec un mot de passe :

  1. Un administrateur appelle POST /api/manage/auth/invite-link, qui renvoie une invitation signée en HMAC-SHA256 et limitée à un couple (tenant, site) (signée avec MANAGE_INVITE_SECRET).
  2. Le destinataire ouvre …/manage/onboard?d=<payload>.
  3. POST /api/auth/manage-invite-accept revérifie le HMAC, provisionne l'utilisateur et définit le cookie __Secure-authjs.session-token.

Clés API de feed

Certains sous-systèmes en lecture seule disposent de leurs propres clés à portée limitée plutôt que d'une session utilisateur :

  • FeedApiKey — une clé hachée avec un préfixe feed_ pour les feeds de contenu. Chaque clé dispose d'un rateLimit horaire, d'une liste d'autorisation d'IP optionnelle (CIDR), d'un expiresAt et d'un ensemble de permissions. Gérée via le router tRPC feedApiKeys.
  • LiveChatApiKey — utilisée par le widget de chat en direct intégrable.

Ce sont l'exception, pas la règle — l'API générale utilise des sessions / JWT Bearer.

Portée locataire et site

Votre identité détermine le locataire au nom duquel vous agissez, mais beaucoup d'appels ont aussi besoin d'une portée site. Vous pouvez fixer les deux explicitement avec des en-têtes — voir tenancy :

X-Tenant-Id: <tenant uuid>
X-Site-Id:   <site uuid>

Sans eux, le serveur se rabat sur le locataire/site sélectionné dans votre session (cookies) ou sur l'hôte de la requête.

Étapes suivantes