Utiliser les API

Pré-requis

Pour utiliser une API, vous devez au préalable avoir :

  • déclaré une application sur l'Emploi Store Développeurs
  • souscrit à une API afin d'obtenir un identifiant client et une clé secrète

 

Identifiants

Un identifiant client et une clé secrète vous sont délivrés par application lorsque vous souscrivez à une première API.

Conservez précieusement ces informations nécessaires pour requêter les API. Vous les retrouverez à tout moment sur la page de configuration de votre application accessible depuis le tableau de bord.

Veillez à protéger votre identifiant client et clé secrète en suivant ces bonnes pratiques :

  • Ne faites pas figurer vos identifiants en clair dans le code source de votre application mais enregistrez-les dans des variables d'environnement ou dans des fichiers dédiés protégés
  • Retirez ceux devenus inutiles et informez le support aux développeurs qui les supprimera
  • Lorsque vous publiez du code sur une plateforme de gestion de versions, assurez-vous que vos identifiants n'apparaissent pas
  • La clé secrète doit être uniquement présente sur la partie serveur de votre application

 

Protocoles et standards

  • Les API exposées respectent les contraintes de l'architecture REST
  • Les API sont sécurisées via le protocole OAuth 2.0 et respectent le standard OpenID Connect
  • OAuth 2.0 et OpenID Connect imposent l'utilisation de HTTPS (TLS V1.2 minimum) pour tous les échanges effectués compte tenu de la sensibilité des données qui transitent
  • Les ressources sont distribuées au format JSON

 

Pôle Emploi Access Management (PEAM)

Il s'agit d'un dispositif d'autorisation basé sur le protocole OAuth 2.0 et intégrant le standard OpenID Connect. Il apporte les fonctionnalités suivantes :

  • la délégation de l'authentification des utilisateurs de votre application avec leur compte Pôle emploi,
  • un mécanisme d'authentification unique sur l'ensemble des services Pôle emploi,
  • un moyen d'obtenir des informations sur l'utilisateur connecté à votre application (via consentement).

La solution se décline en trois royaumes, chacun adressant une population d'utilisateurs :

Population d'utilisateurs URL Royaume
Demandeurs d'emploi et candidats https://authentification-candidat.pole-emploi.fr /individu
Entreprises et recruteurs https://entreprise.pole-emploi.fr /employeur
Partenaires https://entreprise.pole-emploi.fr /partenaire

 

Cinématiques OAuth

La cinématique OAuth à implémenter dépend de votre besoin d'authentifier ou non l'utilisateur final de votre application avec son compte Pôle emploi :

 

Jetons

Selon la cinématique retenue, vous rencontrerez les types de jeton suivants :

Type de jeton Cinématique Description Durée de validité
Access token

Client credentials grant
Authorization code flow

C'est le jeton représentant l'autorisation donnée au client. Il est utilisé pour tous les échanges entre l'application cliente et le serveur de ressources afin d'accéder aux données. 25 minutes
Authorization code

Uniquement utilisé dans la cinématique Authorization code flow (avec authentification utilisateur)

Émis par le serveur d'autorisation, il indique le consentement de l'utilisateur et permet la récupération de l'access token.

60 secondes
Id token

Uniquement utilisé dans la cinématique Authorization code flow (avec authentification utilisateur)

C'est le jeton qui contient les informations sur l'authentification de l'utilisateur final.

2 heures et 30 minutes


Un jeton peut cesser de fonctionner pour l'une des raisons suivantes :

  • sa durée de validité est dépassée
  • l'utilisateur connecté à votre application est revenu sur son consentement

Veillez à rendre votre code résilient en considérant ces évènements.

 

Scopes

Le scope est l’élément central de la gestion des accès à une API et à ses ressources ; il caractérise un périmètre fonctionnel limité. Le développeur d’une application interroge une API en précisant les scopes souhaités. L'usage de certains scopes nécessite le consentement de l'utilisateur si la ressource interrogée expose des données personnelles.

Le tableau suivant récapitule les scopes utilisés par Pôle emploi :

Scope Description Exemple
application_[Identifiant client]

Obligatoire

Doit être passé sur tous vos appels afin d'identifier votre application

application_PAR_libappli_b939f66822c6c0
api_[Identifiant de l'API][Version]

Obligatoire

Permet d'autoriser votre application à accéder à l'API correspondante (si plusieurs API, séparer ces scopes par des espaces)

api_labonneboitev1
[Scopes applicatifs]

Facultatif

Permet d'autoriser votre application à accéder aux données métiers correspondantes, ils sont définis par API (si plusieurs scopes applicatifs, séparer ces scopes par des espaces)

email profile

 

Quota

Un mécanisme de gestion des quotas permet de réguler le nombre d'appels aux API et d'optimiser le partage des ressources entre applications. Deux niveaux de quotas sont déclinés :

  • Un quota maximum est défini pour chaque API, il permet d’assurer la disponibilité du service (exemple : l’API Infotravail supporte une charge maximale de 100 appels par seconde, le quota maximum de cette API sera donc fixé à 100 appels par seconde)
  • Un quota maximum par application permet d'équilibrer le nombre de requêtes par application et par seconde entre toutes les applications (exemple : pour l’utilisation de l’API Infotravail, chaque application dispose d’un quota maximum de 4 appels par seconde).

Ces quotas ne constituent en aucun cas un engagement de service, ils contribuent au bon fonctionnement de l’écosystème.

En cas de dépassement d’un quota, une erreur HTTP 429 (Too Many Requests) est retournée avec un en-tête Retry-After correspondant au nombre de secondes à attendre avant d'être autorisé à réémettre la requête. Utilisez le dans vos développements pour séquencer vos appels afin de garantir une continuité de service à vos utilisateurs.

 

Versionning

Les API sont versionnées. Ainsi, la publication d'une API v3 provoque la dépréciation de l'API v2. Cette dernière reste opérationnelle en attendant que l'ensemble des applications ait migré sur la v3.