Passer au contenu principal

Gestion des zones d'accès (/v2/access-zones)

Mis à jour cette semaine

Cette section détaille les endpoints pour créer, lister, modifier et supprimer les zones d'accès, qui sont utilisées pour gérer les autorisations sur les métriques.

Lister toutes les zones d'accès

Description

Cette requête récupère une liste de toutes les zones d'accès configurées dans le système, avec la possibilité de filtrer et de paginer les résultats.

GET /v2/access-zones

Scope

Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:read.

Paramètres

  • name (string, optionnel) : Filtre les zones dont le nom contient cette chaîne.

  • includeGroups (boolean, optionnel) : Si true (défaut), inclut la liste des ID de groupes associés à chaque zone.

  • limit (integer, optionnel) : Nombre de résultats par page (défaut: 50).

  • paginationKey (string, optionnel) : Clé pour obtenir la page de résultats suivante (voir gestion de la pagination)

Ces paramètres doivent être ajoutés à la fin de l'URL pour construire la chaîne de requête. Le premier est précédé d'un "?" et les suivants sont séparés par un "&".

Syntaxe générale de la requête GET :

.../access-zones?name=[filtre_nom]&includeGroups=[true|false]&limit=[limite]

Exemple de requête

# Commande pour lister toutes les zones d'accès 
 curl -X GET \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/access-zones' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Réponses

Exemple de réponse valide (200 OK)

{ 
   "data": [ 
     { 
       "id": "4e1daf3a-9a1c-4c54-a6ea-f826e03c4270", 
       "name": "#DefaultAccessZoneRead", 
       "groups": [ 
         "67918ae6-f285-4bfc-b23e-e08baa5e275b" 
       ], 
       "accessType": "Read", 
       "isDefault": true 
     } 
   ], 
   "paginationInfo": { 
     "count": 1, 
     "isComplete": true 
   }, 
   "statusCode": 1010, 
   "message": "OK" 
 }

Gestion de la Pagination (isComplete)

Se référer au paragraphe de gestion de la pagination.

Erreurs Courantes :

Veuillez vous référer à la liste des erreurs courantes.

Lister mes zones d'accès

Description

Cette requête récupère la liste des zones d'accès auxquelles l'utilisateur authentifié appartient.

GET /v2/access-zones/me

Scope

Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:read.

Exemple de requête

# Commande pour lister mes propres zones d'accès 
 curl -X GET \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/access-zones/me' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Réponses

Exemple de réponse valide (200 OK)

{ 
   "data": [ 
     { 
       "id": "4e1daf3a-9a1c-4c54-a6ea-f826e03c4270", 
       "name": "#DefaultAccessZoneRead", 
       "accessType": "Read", 
       "isDefault": true 
     } 
   ], 
   "statusCode": 1010, 
   "message": "OK" 
 }

Erreurs Courantes :

Veuillez vous référer à la liste des erreurs courantes.

Créer une nouvelle zone d'accès

Description

Cette requête permet de créer une nouvelle zone d'accès.

POST /v2/access-zones

Scope

Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:admin.

Corps de la requête

  • name (string, obligatoire) : Nom unique de la zone d'accès.

  • accessType (string, obligatoire) : Type d'accès (Read, Write, ou ReadWrite).

  • groups (liste de uuid, optionnel) : Liste des ID des groupes d'utilisateurs à associer à cette zone.

Les paramètres suivants doivent être fournis dans le corps de la requête, au format JSON.

Syntaxe générale du corps de la requête : 

{ 
   "name": "nom_unique_de_la_zone", 
   "accessType": "Read | Write | ReadWrite", 
   "groups": [ "uuid_groupe_1", "uuid_groupe_2" ] 
 }

Exemple de requête

# Commande pour créer une nouvelle zone d'accès 
 curl -X POST \ 
   --url 'https://xxx.indaba.api.indasuite.io-base.com/v2/access-zones' \ 
 
   # ----- En-têtes ----- 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: application/json' \ 
 
   # ----- Corps de la requête ----- 
   -d ' 
   { 
     "name": "TestZone_API_Creation", 
     "accessType": "ReadWrite" 
   } 
   '

Réponses

Exemple de réponse valide (200 OK)

{ 
   "data": { 
     "id": "0894d6cc-9234-4cba-82ad-c1bacaf71a07", 
     "name": "TestZone_API_Creation", 
     "accessType": "ReadWrite", 
     "isDefault": false 
   }, 
   "statusCode": 1010, 
   "message": "OK" 
 }

Erreurs Courantes :

Veuillez vous référer à la liste des erreurs courantes.

Obtenir les détails d'une zone d'accès

Description

Cette requête récupère la configuration complète d'une seule zone d'accès via son ID.

GET /v2/access-zones/{accessZoneId}

Scope

Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:read.

Paramètres

  • accessZoneId (uuid, obligatoire) : ID de la zone d'accès.

Cette requête utilise un paramètre de chemin, qui est intégré directement dans l'URL.

Syntaxe générale de la requête GET :

.../access-zones/[uuid_de_la_zone_d_acces]

Exemple de requête

# Commande pour obtenir la zone avec l'ID '0894d6cc-...' 
 curl -X GET \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/access-zones/0894d6cc-9234-4cba-82ad-c1bacaf71a07' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Réponses

Exemple de réponse valide (200 OK) : 

{ 
   "data": { 
     "id": "0894d6cc-9234-4cba-82ad-c1bacaf71a07", 
     "name": "TestZone_e3707275", 
     "accessType": "ReadWrite", 
     "isDefault": false 
   }, 
   "statusCode": 1010, 
   "message": "OK" 
 }

Erreurs Courantes :

Veuillez vous référer à la liste des erreurs courantes.

Mettre à jour une zone d'accès

Description

Cette requête permet de modifier le nom et le type d'accès d'une zone existante.

PUT /v2/access-zones/{accessZoneId}

Scope

Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:admin.

Paramètres

  • accessZoneId (uuid, obligatoire) : ID de la zone d'accès à modifier.

Cette requête utilise un paramètre de chemin, qui est intégré directement dans l'URL.

Syntaxe générale de l'URL :

.../access-zones/[uuid_de_la_zone_d_acces]

Corps de la requête

  • name (string, obligatoire) : Le nouveau nom de la zone.

  • accessType (string, obligatoire) : Le nouveau type d'accès (Read, Write, ReadWrite).

Les champs suivants doivent être fournis dans le corps de la requête, au format JSON.

Syntaxe générale du corps de la requête : 

{ 
   "name": "nouveau_nom_de_la_zone", 
   "accessType": "Read | Write | ReadWrite" 
 }

Exemple de requête

# Commande pour mettre à jour une zone d'accès 
 curl -X PUT \ 
   --url 'https://xxx.indaba.api.indasuite.io-base.com/v2/access-zones/0894d6cc-9234-4cba-82ad-c1bacaf71a07' \ 
 
   # ----- En-têtes ----- 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: application/json' \ 
 
   # ----- Corps de la requête ----- 
   -d ' 
   { 
     "name": "TestZone_updated_name", 
     "accessType": "Read" 
   } 
   '

Réponses

Exemple de réponse valide (200 OK) : 

{ 
   "data": { 
     "id": "0894d6cc-9234-4cba-82ad-c1bacaf71a07", 
     "name": "TestZone_updated_name", 
     "accessType": "Read", 
     "isDefault": false 
   }, 
   "statusCode": 1010, 
   "message": "OK" 
 }

Erreurs Courantes :

Veuillez vous référer à la liste des erreurs courantes.

Modifier les groupes d'une zone d'accès (Patch)

Description

Cette requête permet d'ajouter et/ou de retirer des groupes d'utilisateurs d'une zone d'accès sans modifier ses autres propriétés.

PATCH /v2/access-zones/{accessZoneId}/groups

Scope

Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:admin.

Paramètres

  • accessZoneId (uuid, obligatoire) : ID de la zone d'accès à modifier.

Cette requête utilise un paramètre de chemin, qui est intégré directement dans l'URL.

Syntaxe générale de l'URL :

.../access-zones/[uuid_de_la_zone_d_acces]/groups

Corps de la requête

  • groupsToAdd (liste de uuid, optionnel) : Liste des ID de groupes à ajouter.

  • groupsToRemove (liste de uuid, optionnel) : Liste des ID de groupes à retirer.

Les champs suivants doivent être fournis dans le corps de la requête, au format JSON.

{ 
   "groupsToAdd": [ "uuid_groupe_a_ajouter_1" ], 
   "groupsToRemove": [ "uuid_groupe_a_retirer_1" ] 
 }

Exemple de requête

# Commande pour ajouter un groupe à une zone 
 curl -X PATCH \ 
   --url 'https://xxx.indaba.api.indasuite.io-base.com/v2/access-zones/0894d6cc-9234-4cba-82ad-c1bacaf71a07/groups' \ 
 
   # ----- En-têtes ----- 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: application/json' \ 
 
   # ----- Corps de la requête ----- 
   -d ' 
   { 
     "groupsToAdd": [ "6dbdeed1-8ab4-4d34-abd9-b1e5b67bb6b0" ], 
     "groupsToRemove": [] 
   } 
   '

Réponses

Exemple de réponse valide (200 OK) : 

{ 
   "statusCode": 1010, 
   "message": "OK" 
 }

Erreurs Courantes :

Veuillez vous référer à la liste des erreurs courantes.

Vérifier mon appartenance à une zone d'accès

Description

Cette requête spéciale (HEAD) permet de vérifier si l'utilisateur authentifié fait partie d'une zone d'accès, sans retourner de corps de message. La réponse est contenue dans le code de statut HTTP.

HEAD /v2/access-zones/{accessZoneId}/users

Scope

Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:write.

Paramètres

  • accessZoneId (uuid, obligatoire) : ID de la zone d'accès à vérifier.

Cette requête utilise un paramètre de chemin, qui est intégré directement dans l'URL.

Syntaxe générale de la requête HEAD :

.../access-zones/[uuid_de_la_zone_d_acces]/users

Exemple de requête

# Commande pour vérifier si je suis dans la zone '0894d6cc-...' # L'option -I effectue une requête HEAD 
 curl -I \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/access-zones/0894d6cc-9234-4cba-82ad-c1bacaf71a07/users' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Réponses

Exemple de réponse valide (200 OK) :

Un code de statut HTTP/1.1 200 OK sans corps de message indique que l'utilisateur fait partie de la zone.

Erreurs Courantes :

Veuillez vous référer à la liste des erreurs courantes.

Supprimer une zone d'accès

Description

Cette requête supprime une zone d'accès. Attention, les métriques utilisant cette zone d'accès (autorisation) seront inaccessibles si aucune autre autorisation n'est positionnée.

DELETE /v2/access-zones/{accessZoneId}

Scope

Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:admin.

Paramètres

  • accessZoneId (uuid, obligatoire) : ID de la zone d'accès à supprimer.

Cette requête utilise un paramètre de chemin, qui est intégré directement dans l'URL.

Syntaxe générale de la requête DELETE :

.../access-zones/[uuid_de_la_zone_d_acces]

Exemple de requête

# Commande pour supprimer la zone d'accès '0894d6cc-...' 
 curl -X DELETE \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/access-zones/0894d6cc-9234-4cba-82ad-c1bacaf71a07' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Réponses

Exemple de réponse valide (200 OK) : 

{ 
   "statusCode": 1010, 
   "message": "OK" 
 }

Erreurs Courantes :

Veuillez vous référer à la liste des erreurs courantes.

Gestion de la Pagination (isComplete)

Pour garantir de bonnes performances, l'API peut diviser les réponses contenant un grand nombre de résultats (par exemple, une longue liste de métriques) en plusieurs "pages". Certaines réponses contiennent un champ booléen nommé "isComplete", dans l'objet "paginationInfo" pour gérer ce cas.

  • Si isComplete est true : Vous avez reçu toutes les données.

  • Si isComplete est false : Il reste des données à récupérer. Pour obtenir la suite :

    1. Récupérez la valeur du champ "paginationKey" dans la réponse que vous venez de recevoir.

    2. Effectuez une nouvelle requête en y ajoutant "paginationKey" comme paramètre et en attribuant à ce paramètre la valeur récupérée.

    3. Répétez ce processus jusqu'à ce que la réponse finale contienne "isComplete" : true.

Erreurs courantes

Vous rencontrerez principalement les codes d'erreur HTTP suivants :

  • 400 Bad Request : Votre requête est malformée. Cela peut être dû à un paramètre manquant, un type de donnée incorrect ou un JSON invalide. Le corps de la réponse contiendra un tableau errors détaillant le problème.
    ​

    { 
    "errors": [ 
    { 
    "error": "Field Required", 
    "message": "The xxx field is required." 
    } 
    ], 
    "statusCode": 1050, 
    "message": "Invalid request" 
    }

  • 403 Forbidden : Votre jeton d'authentification est valide, mais vous n'avez pas les droits nécessaires pour cette action. Cela peut arriver pour deux raisons :

    • Votre jeton n'a pas les droits (scope) nécessaires (par exemple, vous tentez d'écrire des données sans avoir le scope metrics:write).

    • Votre jeton a le bon scope, mais votre utilisateur (ou compte de service) n'est pas rattaché à une autorisation qui donne accès à la métrique demandée.

  • 404 Not Found : La ressource que vous essayez d'atteindre n'existe pas. Cela se produit typiquement si vous utilisez un ID incorrect ou si vous demandez une métrique qui n'existe pas.

Avez-vous trouvé la réponse à votre question ?