API Keys

Définition

Une API key est une chaine de caractères qui peut être générée par un utilisateur après son authentification sur Piano Analytics. Une API key vise à être utilisée en requêtant l'API REST AT Internet au lieu de renseigner les identifiants de l'authentification basique.

Favorisez les API Keys

Une API Key donne les mêmes permissions que celles de l'utilisateur qui l'a créé. Si l'utilisateur perd les droits sur un site, alors il ne sera plus en mesure d'utiliser son API key pour obtenir des données de ce site. Si l'utilisateur obtient de nouveaux droits sur un nouveau site, alors il sera en mesure d'utiliser son API key pour obtenir des données de ce site.

L'API key vise à être utilisée avec les URLs REST récupérées de Data Query. Nous vous invitons à utiliser une API key au lieu de renseigner vos identifiants de connexion utilisant la connexion basique lors du requêtage de l'API avec un outil tiers (script ou autre).
Si vous êtes un utilisateur SSO, vous devez utiliser une API key pour requêter l'API REST AT Internet.

Droits pour créer une API Key

Une API key peut seulement être créée par un utilisateur authentifié qui peut manipuler les données. Cet utilisateur doit avoir au moins l'un des rôles suivants :

• Administrateur
• Délégué
• Analyste avancé
• Analyste
• Rôle personnalisé avec l'outil "Manipuler les données"
• Data Supervisor

L'API key est créée, activée, supprimée par chaque utilisateur de façon indépendante.

Afficher vos API Keys existantes

Les API keys sont affichées dans un tableau fournissant à l'utilisateur les informations suivantes :

1. Nom de l'API key
2. Description de l'API key
3. Premiers caractères de l'API key
4. Date de création
5. Date de dernière utilisation
6. Statut de l'API key : Active/Inactive

Créer une API Key

1. Cliquez sur « Voir profil »
   

   

2. Ouvrez l'onglet « API KEYS » 

3. Cliquez sur le bouton « Créer une nouvelle API key »

   
   

4. Renseignez un nom et une description

5. Validez avec le bouton « Créer une nouvelle API key »

6. Copiez l'API key en cliquant sur le bouton Copier et enregistrez-la en lieu sûr

7. Confirmez l'action en cochant la case de confirmation

Utiliser une API Key

En fonction de l'environnement initiant la requête API, vous pouvez vous baser sur différents paramètres :

Depuis un environnement externe comme Postman :

Postman est un programme qui vous permet d'initier des appels API en dehors de votre navigateur en spécifiant des headers de requête et gérant l'authentification. 
Dans Postman ou toute autre solution similaire que vous utilisez pour appeler nos API, vous pouvez vous appuyer sur ces 2 méthodes :

• Header de requête
  Après avoir ajouté votre URL d'appel API dans le champ GET, rendez-vous dans l'onglet Headers et ajoutez un nouveau header de requête x-api-key avec une valeur suivant ce format accesskey_secretkey.
  
  
• Authentification basique
  Vous pouvez vous rendre dans l'onglet Authorization pour sélectionner le type Basic Auth, et renseigner l'Access Key en Username et la Secret Key en Password.
  
  

Depuis un navigateur :

• URL directe standard
  

  Note

  Cette méthode est la moins sécurisée, car vos identifiants pourraient être écoutés/subtilisés par des logiciels malveillants. Si vous pouvez vous appuyer sur une autre méthode, nous vous invitons à faire le changement.
  Récupérez votre URL d'appel API depuis Data Query et initiez l'appel dans un nouvel onglet. 
  Vous verrez ensuite un formulaire de connexion depuis votre navigateur demandant un Username (Access Key) et un Password (Secret Key).
  Renseignez ces champs, appuyez sur Entrer et récupérez vos résultats.
  
  
• Préfixe d'URL
  Récupérez votre URL d'appel API depuis Data Query et ajoutez y votre Access Key et Secret Key sous ce format accesskey:secretkey@ en tant que préfixe de votre appel. 
  Cette méthode passera les Access Key et Secret Key en header de requête quand vous appelerez l'URL et récupérerez vos résultats.
  

  https://3d0860524341:ee5076836541d5g75he2f49e5d133dacc8762ccb@api.atinternet.io/data/v2/json/getData?&columns={d_source_global,m_visits}&sort={-m_visits}&space={s:123456}&period={R:{D:'-1'}}&max-results=50&page-num=1

Modifier une API Key

Depuis le tableau affichant les API keys, l'utilisateur peut éditer chacune d'entre elles pour :

1. Mettre à jour les noms ou description
2. Rendre l'API key inactive

Dès que l'API key est inactive, elle peut être supprimée par son propriétaire.

Securisez vos API Key

Si vous avez recours à des API keys, nous vous invitons à vous assurer de :

• Les conserver dans un lieu sûr.
• Si vous devez partager une API key avec quelqu'un, créer une nouvelle API key avec un nom spécifique et une description dédiée pour la désactiver ou la supprimer dès que vous le pouvez.
• Supprimer les API keys inutiles régulièrement.
• Renouveler les API keys utilisées par vos programmes régulièrement.

Monitorez l'utilisation des API Keys de votre organisation

Vue rapide

Les administrateurs et délégué peuvent voir dans le tableau d'utilisateurs de Droits d'accès, la dernière utilisation d'une API Key par compte.
Ce champ compte chaque tentative d'authentification d'un utilisateur par une de ses API Keys.
Si l'authentification n'est pas permise, mais l'utilisateur est toujours listé parmi vos utilisateurs (par exemple les comptes suspendus), ce champ sera mis à jour avec la date de tentative même si la requête n'a pas été validée.

Vue complète

Les administrateurs de l'organisation sont les seuls utilisateurs qui peuvent accéder à la liste des API-Keys.

La liste des API Keys peut être requêtée via un appel HTTP utilisant la méthode GET sur cette URL : https://api.atinternet.io/api/config/v1/right/manage/organization/current/users/details

Cette adresse requiert l'utilisation d'une API Key, que vous pouvez créer dans votre Profil sous l'onglet du même nom. Cette API Key peut être utilisée en tant que header de requête.

Exemple avec header de requête :

• https://api.atinternet.io/api/config/v1/right/manage/organization/current/users/details 
• x-api-key: ac0481a1ae0f_8c1af********************

Cet appel récupère les API Keys de tous les utilisateurs de la solution. Les résultats sont regroupés par utilisateur.

Exemple de réponse dans le body :

[
{
 "apiKey": [
 {
 "isActive": true,
 "accessKey": "5d6479******",
 "creationDate": "2018-12-13T09:07:40.735Z",
 "lastUseDate": "2019-01-09T09:14:33.014Z"
 }
 ],
 "userId": 5146**,
 "email": email@atinternet.com
}
{
 "apiKey": [
 {
 "isActive": true,
 "accessKey": "5d6479******",
 "creationDate": "2018-12-13T09:07:40.735Z",
 }
 {
 "isActive": false,
 "accessKey": "4dtd479******",
 "creationDate": "2019-01-03T09:07:40.735Z",
 }
 ],
 "userId": 2236**,
 "email": email2@atinternet.com
}
] 

• “isActive” contient la valeur “true” ou “false”. Il représente le statut de l'API Key
• “accessKey” est une chaîne de caractères unique correspondant aux premiers caractères de l'API Key.
• “creationDate” représente la date à laquelle l'utilisateur a créé l'API Key au format YYYY-MMDDTHH:MM.SS.
• “lastUseDate” représente la date à laquelle l'utilisateur a utilisé l'API Key pour la dernière fois au format YYYYMM-DDTHH:MM:SS.
• “userId” correspond à une chaîne de caractères représentant l'utilisateur.
• “email” représente l'adresse e-mail de l'utilisateur.

Dans l'exemple donné plus tôt, on retrouve :

• 2 utilisateurs qui appartiennent à cette organisation.
• L'adresse e-mail du premier utilisateur est email@atinternet.com
  • Cet utilisateur a 1 API Key
  • Cette API Key est active
  • Elle a été créée le 13/12/2018 à 9:07:40
  • Elle a été utilisée pour la dernière fois le 09/01/2019 à 9:14:33
• L'adresse e-mail du second utilisateur est email2@atinternet.com
  • Cet utilisateur a 2 API Keys
  • Aucune d'entre elles n'a jamais été utilisé
  • La première est active
  • La seconde n'est pas active

Les API Keys supprimées ne sont pas affichées dans la réponse.