Documentation sur le fonctionnement de l’API Aidi (AESA) – Aidi

Pourquoi des accès différents de ceux de la plateforme web?

Puisque les systèmes externes d’API Aidi (AESA - Aidi External System API) offrent un accès de niveau administrateur à la plateforme Aidi, nous voulons fournir des accès facilement gérables, attribués pour des périodes fixes, à des fins de développement et d’intégration. Le processus d’authentification implémenté et décrit ci-dessous est basé sur le standard OAuth 2.0.

Glossaire

Identifiants d’accès AESA : Ensemble d’identifiants et de code secret permettant d’accéder à la documentation AESA (Swagger) et de générer un jeton de session requis pour exécuter les appels API. L’identifiant est composé de 12 caractères et le code secret de 32 caractères.

Jeton de session (X-Aidi-Token) : Accréditation utilisée pour effectuer des requêtes avec l’API, pouvant comporter jusqu’à 8096 caractères.

Création d’identifiants d’accès AESA

Utilisation des identifiants d’accès AESA pour créer des jetons de session via Swagger

Précision sur les fonctionnalités d’AESA

Accéder aux identifiants d’accès AESA

Supprimer les identifiants d’accès AESA

Création d’identifiants d’accès AESA

De nouveaux identifiants doivent être créés pour chaque instance individuelle utilisée pour accéder aux paramètres système. Par exemple, les développeurs qui ont besoin d’accéder à des environnements de préproduction devraient se voir attribuer des identifiants. Chaque service automatisé en production doit également se voir attribuer des identifiants individuels. Il n’y a pas de limites au nombre d’identifiants qui peuvent être utilisés simultanément.

L’utilisateur qui crée les identifiants doit avoir un profil d’accès Administrateur dans Aidi.

Dans le menu de gauche de la plateforme web d’Aidi, cliquez sur Paramètres système.
Dans l’onglet Configuration d’AESA, entrez la date d’expiration souhaitée pour les nouvelles informations d’identification.
- Si vous n’entrez pas de date et d’heure, le délai d’expiration de la clé générée est fixé à 30 minutes par défaut.
- Si vous sélectionnez la date et l’heure d’expiration, ça doit être fait en fonction de votre fuseau horaire actuel.
Appuyez sur le bouton Nouvel accès.
Attendez quelques secondes, une nouvelle ligne s’ajoutera à la fin de la liste.

Les codes ID et Secret seront requis ultérieurement pour l’authentification. Nous vous recommandons de les conserver dans un endroit sûr tel qu’un gestionnaire de mot de passe.

⚠️Attention : Le code secret n’est visible qu’immédiatement après avoir été généré et seulement pour l’utilisateur ayant généré l’identifiant. Il sera caché par la suite et il ne pourra pas être récupéré. Un autre identifiant devra être créé.

Utilisation des identifiants d’accès AESA pour créer des jetons de session via Swagger

Plusieurs jetons de session peuvent être créés et utilisés simultanément pour un même ensemble d’informations d’identification (identifiant et code secret). Les jetons de session ne sont valables que pour 30 minutes à compter de leur création.

Étapes d’utilisation

Se connecter à l’interface Swagger AESA (https://nom_de_domaine.aidi.io/v1/apidocs) en utilisant l’identifiant et le code secret générés précédemment comme nom d’utilisateur et mot de passe respectivement.

Ouvrez la section POST /v1/oauth2.0 en cliquant sur l’en-tête.
Cliquez sur le bouton Try it out.

Dans la section body, remplacez « string » dans la chaîne « “client_id” : “string” » par l’identifiant généré précédemment et remplacez « string » dans la chaîne « “client_id”: “secret” » par le code secret généré précédemment.
Cliquez sur le bouton Execute.

Une réponse avec le code de statut 200 devrait s’afficher en dessous avec la réponse suivante :

{

"token_type" : "Bearer",

"access_token" : "<session_token>",

"expires_in" : 1800

}

Copier le jeton de session (<session_token> dans l’exemple ci-dessus) de la réponse (sans les doubles guillemets).

✏️Note : Ce jeton est valide pour une période de 30 minutes.

Sélectionner le endpoint API que vous souhaitez utiliser (par exemple, GET /v1/authed).
Cliquez sur le bouton Try it out.

Collez le jeton (Session Token) dans le champ de saisie de l’en-tête X-Aidi-Token.
Cliquez sur le bouton Execute.

Une section réponse (Responses) apparaîtrait et sera sous-divisé en 3 sections :

Le Curl (Client for URL), qui fournit l’ensemble des informations d’entrée de la requête, dont les headers.
Le Request URL, qui offre l’URL de la requête.
Le Server Response, constitué du Code et du Response body de la requête

Précision sur les fonctionnalités d’AESA

Filtre (Parameters)

Plusieurs des endpoints GET offrent l’option de filtrer les données recueillies afin d’obtenir les entrées répondant à certains critères. L’information des filtres sera toujours définie à partir de l’URL. Afin de connaître la nomenclature utilisée par ces filtres, nous vous invitons à tester la requête à partir de l’interface Swagger. Par exemple, la nomenclature permettant de filtrer des projets par Id est la suivante :

Sachez aussi qu’il est possible d’appliquer plusieurs filtres à la fois.

Voici à quoi ressemble l’URL de la requête si on ajoute, par exemple, le filtre par identifiant d’unité administrative :

La combinaison des filtres supporte uniquement la logique de type ET (AND) et l’ensemble des entrées d’un filtre (par exemple : id=3, …) supporte une logique de type OR (soit id=3 ou id=...). Par conséquent, dans l’exemple ci-dessus, le projet retourné doit avoir l’un des id définis dans le filtre et doit avoir l’un des id d’unité administrative définis dans le filtre.

Structure requise pour les POST, PUT et PATCH

Afin de connaître la structure requise pour les endpoints de type POST, PUT et PATCH, il suffit de naviguer dans la section body, puis de cliquer sur Model. Les entrées ayant un astérisque rouge sont requises pour le succès de l’appel. Voici un exemple :

Accéder aux identifiants d’accès AESA

Le gestionnaire TI qui accède aux identifiants doit avoir un profil d’accès Administrateur.

Dans le menu de gauche de la plateforme web d’Aidi, cliquez sur Paramètres système.

Vous verrez la liste des identifiants déjà créés dans l’onglet Configuration d’AESA.

ID : Indicateur principal d’un ensemble d’information d’identification.
Secret : Ce code n’est visible que pour l’utilisateur l’ayant généré et il n’est affiché que quelques instants après avoir été généré. Il est ensuite caché.
Date de création : Indique l’heure à laquelle les informations d’identification ont été générées par le serveur.
Date de péremption : Horodatage du serveur qui indique le moment auquel les informations d’identification expireront. Noter que les références expirées ne sont pas automatiquement supprimées de la liste.
Dernière session : Indique l’heure à laquelle les informations d’identification ont été utilisées pour la dernière fois pour générer une session.

Supprimer les identifiants d’accès AESA

La suppression d’informations d’identification les rend inutilisables pour créer de nouvelles sessions et les retire de la liste des informations d’identification de l’API. Cette fonction doit être utilisée pour assurer la rotation des informations d’identification, selon les besoins.

L’utilisateur qui accède aux identifiants doit avoir un profil d’accès Administrateur.

Dans le menu de gauche de la plateforme web d’Aidi, cliquez sur Paramètres système et vous verrez la liste des identifiants déjà créés dans l’onglet Configuration d’AESA.

Accédez au menu des 3 points à droite de la ligne à supprimer.
Cliquez sur Supprimer.

La ligne disparaîtra de la liste des informations d’identification. Les identifiants supprimés sont conservés dans les archives d’Aidi à des fins de journalisation interne. Si vous avez besoin d’informations sur d’anciens identifiants (à des fins d’audit, par exemple), veuillez contacter le support Aidi.

Les informations d’identification supprimées ne peuvent plus être utilisées pour générer un jeton de session AESA valide.