ELRM developer Bac à sable

Authentification et portées#

Un jeton porteur par clé, des portées explicites, et un client par clé pour tout ce qui est nominatif.

Le jeton#

Toutes les routes exigent l'en-tête :

Authorization: Bearer pk_live_<identifiant>.<secret>
  • pk_live_… : clé de production · pk_test_… : clé de bac à sable.
  • L'identifiant (pk_live_ + 12 caractères) n'est pas secret : c'est lui qui désigne la clé dans vos échanges avec ELRM, sans jamais dévoiler le secret.
  • Le secret n'est affiché qu'une fois, à la création. ELRM n'en conserve qu'une empreinte : en cas de perte, une nouvelle clé est émise et l'ancienne révoquée.

Traitez le jeton comme un mot de passe : variable d'environnement ou coffre à secrets, jamais dans le code ni dans un dépôt. Il transite uniquement en HTTPS, et toujours depuis un serveur : n'appelez pas l'API depuis un navigateur ou une application mobile, le jeton y serait lisible par n'importe qui.

Ce qui se passe quand ça échoue#

L'API répond 401 unauthorized pour toute clé inconnue, révoquée, expirée ou mal formée, sans distinguer le motif ; 403 forbidden pour un accès suspendu, une adresse IP hors liste ou un droit manquant. C'est délibéré : un attaquant qui teste des jetons n'obtient aucune information. En interne, le motif exact est journalisé et visible par ELRM ; en cas de doute, envoyez-nous le X-Trace-Id de la réponse.

{ "error": { "code": "unauthorized", "message": "Missing or invalid credential.", "details": {}, "trace_id": "…" } }

Une clé peut aussi être restreinte à des adresses IP (liste de CIDR définie avec ELRM). Hors de cette liste : 403 forbidden, là encore sans détail.

Portées (scopes)#

Chaque clé porte une liste de portées, au format <module>:<ressource>:<action>. Appeler une route sans la portée correspondante répond 403 forbidden, même avec un jeton valide.

Portée Donne accès à
clients:analyses:read Vos analyses du besoin : liste et détail
clients:analyses:write Créer une analyse du besoin
clients:apprenants:read Apprenants inscrits, certifications
clients:apprenants:write Inscrire et répartir les apprenants, déposer leurs pièces
clients:documents:read Documents d'un dossier, téléchargement
clients:dossiers:read Votre fiche (GET /me), catalogue à vos prix, dossiers, suivi, événements ; espace client : dossiers, sessions, inscription
clients:dossiers:write Créer un dossier (accepté d'emblée)
clients:factures:read Factures de formation : liste, détail, PDF
formations:mcf:read Catalogue Mon Compte Formation
formations:recommendations:read Référentiel des formations
formations:sessions:read Sessions ouvertes (GET /formations/sessions…, /centres)

Chaque route de la référence annonce la portée qu'elle exige (security du schéma OpenAPI).

Les portées d'une clé ne dépassent jamais les droits API de votre fiche client, réglés par ELRM : ce sont les mêmes droits que ceux de votre espace sur le portail. Une clé peut recevoir tous ces droits (elle suit alors leurs évolutions) ou seulement une partie. Demandez le minimum nécessaire : une clé « catalogue » sans portée nominative ne peut, par construction, lire aucune donnée personnelle.

Une clé, un client#

Les portées disent quoi ; la clé dit pour qui. Chaque clé est rattachée par ELRM à un seul client : le vôtre. Les routes nominatives (/dossiers, /apprenants, /analyses-besoin, /formations à vos prix) n'ont donc pas d'identifiant de client à passer, elles portent implicitement sur lui.

  • GET /me renvoie ce client (identifiant, nom, SIRET) : pratique pour vérifier au démarrage que la clé configurée est la bonne.
  • Un dossier qui n'est pas le vôtre répond 404 not_found : l'API ne confirme pas l'existence de ce qu'elle ne vous montre pas.
  • Une clé qui a les portées nominatives mais aucun client rattaché répond 403 forbidden.
curl https://developer.elrm.app/sandbox/v1/me -H "Authorization: Bearer pk_test_…"

{ "id": "5b3c2f4e-…", "nom": "CERTALIS (bac à sable)", "siret": "00000000000000" }

Rotation d'une clé#

  1. Demandez une nouvelle clé avec les mêmes portées et le même client.
  2. Déployez-la ; les deux clés fonctionnent en parallèle.
  3. Demandez la révocation de l'ancienne. La révocation est immédiate.

Chaque clé peut porter une date d'expiration : passé cette date, 401.