Authentification de l'API : jetons et identifiants

L'API de NEXCLARA reçoit son authentification dans l'en-tête HTTP Authorization, sous forme de jeton porteur. Elle ne lit ni n'émet aucun cookie : elle n'a donc besoin ni de partage d'origine avec authentification, ni de jeton anti-falsification. Deux familles d'identité existent, et aucune ne remplace l'autre : une session humaine n'ouvre pas les opérations machine, et un identifiant machine n'ouvre pas les opérations réservées aux agents.

Session d'un agent

L'ouverture d'une session suit le même parcours que l'écran de connexion :

1. POST /api/v1/auth/login avec la référence de l'institution, l'adresse et le mot de passe. La réponse rend un jeton de session opaque, montré une seule fois, dans l'état « second facteur requis ».
2. POST /api/v1/auth/second-factor avec le code à six chiffres, en présentant ce jeton. La session passe à l'état « authentifié ».
3. Les appels suivants présentent le jeton :

GET /api/v1/me HTTP/1.1
Authorization: Bearer <jeton de session>
X-Request-ID: <identifiant de corrélation facultatif>

La plateforme ne conserve que l'empreinte du jeton. Une session expire après 30 minutes d'inactivité et 12 heures au plus (valeurs par défaut) ; POST /api/v1/auth/logout la révoque. Suspendre ou désactiver un compte révoque toutes ses sessions.

Vérification renforcée

Les actions sensibles (attribution de rôles, suspension, approbation d'une politique, émission d'un identifiant machine…) exigent un second facteur vérifié depuis moins de 10 minutes. POST /api/v1/auth/step-up renouvelle cette vérification avec un nouveau code, sans rouvrir de session.

Identifiants machine

L'administrateur de l'institution émet des identifiants machine depuis ADMIN : un nom, des portées explicites et, au choix, une date d'expiration. Le secret est montré une seule fois ; seule son empreinte est conservée. Un identifiant se révoque immédiatement.

Une seule portée existe aujourd'hui, et une seule opération accepte un identifiant machine : GET /api/v1/integration/whoami, qui exige la portée integration.ping et permet à un système intégré de vérifier son identifiant. Une session humaine y est refusée.

Corrélation

Chaque réponse porte l'en-tête X-Request-ID. Si l'appelant en fournit un, il est repris après nettoyage (lettres et chiffres ASCII, tiret et souligné, 8 à 64 caractères) ; s'il est absent ou inutilisable, la plateforme en génère un. Le même identifiant figure dans le corps de toute réponse d'erreur : c'est la référence à communiquer pour toute investigation (voir Protocole d'erreur).

Ce qui est encore en construction

• aucune opération métier n'est ouverte aux identifiants machine : les dossiers, les imports et les preuves exigent aujourd'hui la session d'un agent habilité ;
• le contrat OpenAPI ne déclare pas encore de schéma de sécurité : la référence de l'API le signale, et cette page en tient lieu ;
• aucune fédération d'identité (OIDC, SAML) avec l'annuaire de l'institution.