Référence de la Management API

Documentation de la Management API d’Auth0

Version : 2.0 (actuelle)

L’Auth0 Management API est un ensemble de points de terminaison permettant d’effectuer des tâches administratives par programmation et doit être utilisée par des serveurs back-end ou des parties de confiance. De manière générale, tout ce qui peut être fait dans l’Auth0 Dashboard peut aussi être fait au moyen de cette API.

Cette API est distincte de la Auth0 Authentication API accessible au public, qui est destinée aux front-ends et aux parties non fiables.

Lorsque vous utilisez les exemples de code inclus dans cette documentation d’API, les requêtes doivent être envoyées avec un Content-Type de application/json. Tous les points de terminaison acceptent une charge utile d’une taille maximale de 1 mégaoctet.

La documentation de l’Auth0 Management API suit le schéma OpenAPI v3.1 de l’Auth0 Management API. Veuillez noter que la prise en charge du schéma OpenAPI v3.1 est actuellement en version Beta.

​

Authentification

L’utilisation de l’Auth0 Management API nécessite un jeton d’accès pour l’Auth0 Management API. Pour savoir comment demander ce jeton, consultez Jetons d’accès pour l’Auth0 Management API.

L’Auth0 Management API utilise des JSON Web Tokens (JWT) pour authentifier les requêtes. La claim scopes du jeton d’accès pour l’Auth0 Management API indique quelles méthodes de requête peuvent être exécutées lors d’un appel à cette API. L’exemple de jeton désérialisé sur cette page accorde un accès en lecture seule aux utilisateurs et un accès en lecture/écriture aux connexions. Toute tentative d’exécuter une méthode de requête non autorisée par les scopes définis entraînera une réponse 403 Forbidden.

{
  "aud": "m8DAxghyfE0KdpzogfXgMSxrkCSdKVEF",
  "scopes": {
    "connections": {
      "actions": ["read", "update"]
    }
  },
  "iat": "1446056652",
  "jti": "7e9c6a991f5a227fb7ebaa522536ae4c"
}

Pour effectuer des requêtes à l’API, envoyez le token d’API dans l’en-tête HTTP Authorization au moyen du schéma d’authentification Bearer.

curl -H "Authorization: Bearer eyJhb..." https://@@TENANT@@/api/v2/users

​

Corrélation des requêtes

Un ID de corrélation est un identificateur unique (jusqu’à 64 caractères) associé à une seule opération de la Management API et permet de suivre ces opérations dans les logs du tenant. Pour en savoir plus, consultez Logs.

L’API accepte un ID de corrélation fourni par le client s’il est envoyé dans l’en-tête HTTP X-Correlation-ID avec les méthodes POST, PUT, PATCH et DELETE.

curl -H "Authorization: Bearer eyJhb..." -H "x-correlation-id: client1_xyz" https://@@TENANT@@/api/v2/users

Si une valeur d’en-tête X-Correlation-ID de plus de 64 caractères est fournie, seuls les 64 premiers caractères seront affichés dans les logs.

"references": {
  "correlation_id": "client1_xyz"
}

​

Pagination

La pagination est une technique utilisée par les API pour diviser de grands ensembles de données en pages gérables, ce qui réduit la quantité de données renvoyées dans chaque réponse. Deux grands types de pagination sont couramment utilisés dans les API : la pagination par décalage et la pagination par point de contrôle. Chacune présente des avantages distincts et des cas d’utilisation qui varient selon la taille de l’ensemble de données et les exigences de récupération.

L’Auth0 Management API prend en charge les deux types de pagination sur plusieurs points de terminaison, comme GET /api/v2/clients et GET /api/v2/logs. Lorsque les deux options sont offertes, la pagination par point de contrôle est recommandée en raison de sa meilleure efficacité et de sa plus grande stabilité pour les grands ensembles de données.

​

Pagination par décalage

La pagination par décalage est une méthode simple et largement utilisée pour paginer des ensembles de données comptant jusqu’à environ 1 000 éléments. Cette approche utilise les paramètres page et per_page pour définir le point de départ et le nombre d’éléments sur chaque page.

• Paramètres :
  • page : Le numéro de la page à récupérer, indexé à partir de zéro. La valeur par défaut est 0 s’il n’est pas indiqué.
  • per_page : Le nombre d’éléments à renvoyer par page. Pour les tenants Public Cloud, le maximum est de 50; pour Private Cloud, le maximum est de 100. S’il n’est pas indiqué, la valeur par défaut correspond à la moitié du maximum.

Exemple de requête de pagination par décalage :

curl -L "https://@@TENANT@@/api/v2/clients?per_page=10&page=2" \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Accept: application/json'

Dans la pagination par offset :

• Si page * per_page dépasse le nombre total de résultats, un tableau vide est renvoyé.
• Chaque requête de page recalcule l’offset, ce qui peut nuire aux performances avec des ensembles de données volumineux. La pagination par offset convient généralement mieux aux collections qui ont peu de chances de dépasser 1 000 éléments.

​

Pagination par point de contrôle

La pagination par point de contrôle, aussi appelée pagination par curseur ou par jeton, est optimisée pour les grands ensembles de données. Cette méthode utilise un ID de point de contrôle next fourni par le serveur pour récupérer les pages suivantes dans une séquence vers l’avant uniquement. L’ID de point de contrôle next est inclus dans la réponse lorsque des résultats supplémentaires sont disponibles.

Pour poursuivre la pagination, utilisez l’ID de point de contrôle next dans le paramètre de requête from de la requête suivante. Cet ID est opaque et doit être transmis sans modification.

• Paramètres :
  • from : L’ID de point de contrôle next de la réponse précédente, utilisé pour récupérer la page suivante de résultats.
  • take : Le nombre d’éléments à renvoyer par page. Pour les tenants Public Cloud, le maximum est 50; pour Private Cloud, le maximum est de 100. Par défaut, la valeur correspond à la moitié du maximum si elle n’est pas fournie.

Exemple de requête de pagination par point de contrôle :

curl -L "https://@@TENANT@@/api/v2/clients?take=10&from=Cg1HRUY3NEszUERFME40GgAiAQgCEj..." \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Accept: application/json'

​

Expiration de l’ID de point de contrôle

Lors de l’utilisation de la pagination par point de contrôle, il est important de tenir compte de la durée de validité de chaque ID de point de contrôle next. L’ID de point de contrôle doit être utilisé de façon séquentielle, et chaque ID n’est valide que pour une durée limitée afin d’assurer la cohérence des données.

Remarque

L’ID de point de contrôle next est valide pendant 24 heures à partir de sa création. S’il expire, une nouvelle requête est nécessaire pour repartir du début du jeu de données. Pensez à mettre les résultats en cache si un délai important risque de s’écouler entre les requêtes.

​

Contraintes de progression vers l’avant

La pagination par point de contrôle s’effectue uniquement vers l’avant. Évitez d’utiliser l’ID de point de contrôle pour revenir en arrière ou pour envoyer des requêtes hors séquence, car cela peut provoquer des erreurs. Utilisez toujours l’ID de point de contrôle next de la réponse précédente.

​

Choisir entre la pagination par décalage et la pagination par point de contrôle

Lorsque les deux types de pagination sont pris en charge :

• Utilisez la pagination par point de contrôle pour gérer efficacement de grands ensembles de données.
• Utilisez la pagination par décalage pour les plus petits ensembles de données (généralement moins de 1 000 éléments), car elle est plus simple à mettre en œuvre, mais moins efficace pour les grandes collections.

​

Bonnes pratiques pour gérer la pagination

• Cohérence des données : Chaque requête paginée reflète l’état des données au moment où la requête est effectuée. Si des données sont mises à jour ou supprimées, certains éléments peuvent être ignorés ou apparaître en double. La pagination par point de contrôle peut contribuer à rendre la pagination plus fluide dans les ensembles de données dynamiques.
• Stockage des points de contrôle : Pour la récupération de grands volumes de données, envisagez de stocker des points de contrôle après chaque page afin de pouvoir reprendre au dernier point de contrôle en cas d’interruption.

Cette approche permet une récupération des données efficace et stable pour les grands ensembles de données, conformément aux options de pagination de l’Auth0 Management API.

​

Tester avec un jeton d’accès

Vous pouvez obtenir un jeton d’accès à des fins de test. Pour en savoir plus, consultez Obtenir des jetons d’accès à la Management API pour les tests.