Aller au contenu principal

Authentification de l'API

Les appels à l'API portent un jeton d'accès émis par la plateforme elle-même. Il n'existe ni flux « client credentials », ni clé d'API, ni compte de service : un programme se connecte avec un compte utilisateur de l'organisation, et agit avec les droits de son rôle. Créez-lui un compte dédié, au rôle strictement nécessaire (Habilitations).

1. Se connecter​

curl -X POST "https://<adresse-de-la-plateforme>/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "<adresse du compte>", "password": "<mot de passe>"}'

Sans second facteur, la réponse porte les jetons :

{
  "access_token": "<jeton d'accès>",
  "refresh_token": "<jeton de renouvellement>",
  "token_type": "bearer",
  "expires_in": 900
}

expires_in est la durée de vie du jeton d'accès, en secondes (quinze minutes par défaut).

2. Le second facteur​

Si le compte a une double authentification, ou si l'organisation l'impose, la connexion répond par un défi (mfa_required, mfa_token, valable quelques minutes). Envoyez alors le code à six chiffres de l'application d'authentification :

curl -X POST "https://<adresse-de-la-plateforme>/api/v1/auth/mfa/verify" \
  -H "Content-Type: application/json" \
  -d '{"mfa_token": "<jeton du défi>", "code": "123456"}'

La réponse porte les mêmes jetons qu'une connexion sans second facteur. Un compte que la politique oblige à enrôler un second facteur (mfa_setup_required) doit d'abord l'activer depuis l'écran de connexion.

3. Appeler l'API​

curl "https://<adresse-de-la-plateforme>/api/v1/orgs/<organisation>/services/restitutions/catalogue" \
  -H "Authorization: Bearer <jeton d'accès>"

L'organisation se désigne dans le chemin ; le compte doit en être membre. L'en-tête X-Consolidated demande la vue consolidée, si le compte y est habilité.

4. Renouveler le jeton​

curl -X POST "https://<adresse-de-la-plateforme>/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<jeton de renouvellement>"}'

Les erreurs​

  • 401 : jeton absent, expiré ou invalide — reconnectez-vous ou renouvelez le jeton.
  • 403 : jeton valide, mais le rôle du compte n'a pas le droit demandé, ou le module est fermé à l'organisation.

Le verrouillage du compte après des échecs répétés vaut aussi pour les appels de l'API. Voir Authentification et sécurité.