Appeler l'API

L'API est organisée en sous-parties :

• /ext/, une partie ne répondant à aucune règle d'authentification des requêtes ;
• /public/, rassemblant les routes accessibles publiquement uniquement sur présentation d'une clef API valide ;
• /user/, rassemblant les routes accessibles sur présentation d'une clef API valide ainsi que d'un token utilisateur valide ;
• /pro/, rassemblant les routes de gestion de fiche établissement (informations de la fiche, publication sur les flux, etc.) et accessible sur présentation d'une clef API valide ainsi que d'un token utilisateur valide.

TIP

La présence d'informations d'authentification (clef API, token) sur des routes sur lesquelles ce n'est pas nécessaire n'entraîne pas d'erreur de l'API.

En d'autres termes, il est possible de fournir une clef API et un token dans tous les cas, même en appelant /ext/.

Clef API

La présentation de la clef API se fait via le header X-API-KEY.

X-API-KEY: my_api_key

Token

Un token est délivré par l'API et permet d'authentifier les requêtes "en tant que" un utilisateur donné.

Il est valide pendant 24h.

Génération d'un token via user/password

Un token utilisateur se génère en appelant la route /public/token et en fournissant un payload contenant les informations de l'utilisateur :

POST /public/token

{
	"grant_type": "password",
	"username": "user_email@email.com",
    "password": "user_password"
}

En réponse à cette requête, sous réserve que les informations de l'utilisateur soient correctes, l'API retournera :

{
	"access_token": "YjQwYWY1NTMyOTFiYjBjYTNkM2M2MzBmNzFjM2RkMmVkYTAyYTNmMDRiOTY1YzU1ZTQzMDU4NTU4ZWUyNGY0ZQ",
	"expires_in": 86400,
	"token_type": "bearer",
	"scope": "user",
	"refresh_token": "NDhlZGY0NTJlNTU2NWM3MmY0YjhkYWRkNDg3YjRmNDhhN2M2NzIxNzhlZTgyZTcxOTY5MDdjMjQ2OWRkOTFjNg"
}

Ici, le champ access_token nous fourni le token à utiliser dans nos futures requêtes.

Génération d'un token via refresh token

Dans le payload retourné par l'API, un refresh_token est présent.

Sa date d'expiration est bien supérieure à celle de l'access_token : 200jours. Il est cependant inutilisable en tant que tel pour s'identifier auprès de l'API.

En revanche, il peut être utilisé afin de re-générer un access_token :

{
	"grant_type": "refresh_token",
	"refresh_token": "NDhlZGY0NTJlNTU2NWM3MmY0YjhkYWRkNDg3YjRmNDhhN2M2NzIxNzhlZTgyZTcxOTY5MDdjMjQ2OWRkOTFjNg"
}

L'API répondra à nouveau, sous réserve de la validité du refresh_token :

{
	"access_token": "AbcdYWY1NTMyOTFiYjBjYTNkM2M2MzBmNzFjM2RkMmVkYTAyYTNmMDRiOTY1YzU1ZTQzMDU4NTU4ZWUyNGY012",
	"expires_in": 86400,
	"token_type": "bearer",
	"scope": "user",
	"refresh_token": "AvbcZGY0NTJlNTU2NWM3MmY0YjhkYWRkNDg3YjRmNDhhN2M2NzIxNzhlZTgyZTcxOTY5MDdjMjQ2OWRkOTF012"
}

Utilisation de l'access_token

L'access_token peut être présenté lors de l'appel à l'API via le header Authorization :

Authorization: Bearer {access_token}