Nous allons décrire dans ce document le fonctionnement de la couche « API » de Nicoka, ce fonctionnement est commun à l’ensemble de nos modules. Il s’agit d’une API RestFull ; respectant les normes suivantes :

Chemin

Pour accéder à votre API vous depuis un compte en production vous devez utiliser le chemin suivant :

Si vous souhaitez tester l’API depuis un compte d’essai vous devez utiliser le chemin
suivant :

Utilisateur API

Il est fortement conseiller d’utiliser un utilisateur dédié pour se connecter à l’API. Pour cela vous devez aller dans le Menu « Administration » / « Utilisateur API » et créer votre utilisateur. L’adresse email de cet utilisateur doit exister, car elle sera utiliser pour vous notifier en cas d’erreur.

Accès

Comprendre le flux d'authentification OAuth avec login et mot de passe

Utilisez le flux d'authentification login-mot de passe pour vous authentifier lorsque le consommateur dispose déjà des informations d'identification de l'utilisateur.
Dans ce flux, les informations d'identification de l'utilisateur sont utilisées par l'application pour demander un jeton d'accès, comme indiqué dans les étapes suivantes.

Avertissement

Ce flux d'authentification OAuth transmet les informations d'identification de l'utilisateur. Utilisez ce flux d'authentification uniquement lorsque nécessaire. Aucun jeton d'actualisation n'est émis.

1. Pour accéder à l’API vous avez besoin d’un jeton (« Token »), afin de générer votre jeton d’accès vous devez effectuer une première requête de type POST à l’adresse suivante :




https://{account_subdomain}.nicoka.com/api/login










Paramètres	Description
login	Votre email de login Nicoka
password	Votre mot de passe Nicoka




2. Nicoka vérifie les informations d'identification de l'utilisateur et, en cas de succès, envoie une réponse à l'application avec le jeton d'accès. Cette réponse contient la valeur suivante :

   
   
   
   
   
   
   

   Paramètres	Description
   token	Votre jeton d'accès

   
   

   Exemples de réponse :

   
   

   {
   "token": " eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIiwiZXhwIjoxNTQ4MTAyNTExfQ.a96HA5xozI_6TE65ybC5RsXdOfSuHd4Wbmhswb-V1nw"
   }

   
   



3. L'application utilise le jeton d'accès fourni pour accéder aux données utilisateurs protégés.

   
   
   • Comme l'utilisateur n'est jamais redirigé pour se connecter à Nicoka dans ce flux, l'utilisateur ne peut pas autoriser directement l'application, et donc il n’y a pas d'actualisation des jetons utilisés. Si votre application nécessite l'actualisation des jetons, vous devez envisager d'utiliser le flux OAuth du serveur Web ou de l'agent utilisateur

Générer un jeton d’accès directement depuis Nicoka

Lorsque vous êtes connectez à Nicoka vous pouvez récupérer votre jeton d’accès actuel, en allant dans vos préférences utilisateurs :

Puis allez dans le menu : « Applications Externes » :

Pour les utilisateurs API vous il suffit de cliquer sur le nom de l’utilisateur depuis la liste des utilisateurs API et d’appuyer sur le bouton « Afficher le jeton d’accès »

Attention

Les jetons ont une durée de vie de 1 an, il faut donc les renouveler avant expiration !