Passer au contenu principal
Version : 2.0 (actuelle) La Management API d’Auth0 est un ensemble de points de terminaison permettant d’effectuer des tâches administratives par programmation et doit être utilisée par des serveurs backend ou des parties de confiance. De façon 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 l’Auth0 Authentication API accessible au public, qui est destinée aux applications frontend 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 la Management API d’Auth0 suit le schéma OpenAPI v3.1 de la Management API d’Auth0. Veuillez noter que la prise en charge du schéma OpenAPI v3.1 est actuellement en version bêta.

​
Authentification

L’utilisation de l’Auth0 Management API nécessite un jeton d’accès pour la Management API. Pour savoir comment demander ce jeton, consultez Jetons d’accès de la Management API. L’Auth0 Management API utilise des JSON Web Tokens (JWT) pour authentifier les requêtes. La revendication scopes du jeton d’accès de la Management API indique quelles méthodes de requête peuvent être exécutées lors de l’appel de 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 l’ensemble de scopes entraînera une réponse 403 Forbidden. 
{
  "aud": "m8DAxghyfE0KdpzogfXgMSxrkCSdKVEF",
  "scopes": {
    "connections": {
      "actions": ["read", "update"]
    }
  },
  "iat": "1446056652",
  "jti": "7e9c6a991f5a227fb7ebaa522536ae4c"
}
Pour effectuer des appels à l’API, envoyez le jeton 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 identifiant unique (jusqu’à 64 caractères) associé à une opération unique de la Management API et permet d’en faire le suivi dans les journaux du locataire. Pour en savoir plus, consultez Logs. L’API accepte un ID de corrélation fourni par l’application s’il est transmis 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 la valeur de l’en-tête X-Correlation-ID dépasse 64 caractères, seuls les 64 premiers seront affichés dans les journaux. 
"references": {
  "correlation_id": "client1_xyz"
}
La pagination est une technique utilisée par les API pour diviser de grands ensembles de données en pages plus faciles à gérer, ce qui réduit la quantité de données renvoyée 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 offre des avantages et des cas d’utilisation distincts selon la taille de l’ensemble de données et les exigences de récupération. Le Management API d’Auth0 prend en charge les deux types de pagination sur de nombreux 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, car elle est plus efficace et plus stable 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 jeux 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 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 locataires du cloud public, le maximum est 50 ; pour le cloud privé, le maximum est 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 décalage :
  • Si page * per_page dépasse le nombre total de résultats, un tableau vide est renvoyé.
  • Chaque requête de page recalcule le décalage, ce qui peut nuire aux performances lorsque les ensembles de données sont volumineux. La pagination par décalage convient généralement mieux aux collections qui risquent peu 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 allant uniquement vers l’avant. L’ID de point de contrôle next est inclus dans la réponse lorsque d’autres résultats 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 tel quel, 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 de résultats suivante.
    • take : le nombre d’éléments à renvoyer par page. Pour les locataires du cloud public, le maximum est de 50 ; pour cloud privé, 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 avec 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

Lorsque vous utilisez une 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 manière séquentielle, chaque ID n’étant valide que pendant 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 à compter de sa création. S’il expire, vous devez envoyer une nouvelle requête pour recommencer au début du jeu de données. Pensez à mettre les résultats en cache si un délai prolongé risque de s’écouler entre les requêtes.

​
Contraintes de pagination unidirectionnelle

La pagination par point de contrôle est unidirectionnelle. Évitez d’utiliser l’ID du point de contrôle pour revenir en arrière ou pour effectuer des requêtes hors séquence, car cela peut entraîner 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 ensembles de données plus petits (généralement moins de 1 000 éléments), car elle est plus simple à implémenter, 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 omis ou apparaître en double. La pagination par point de contrôle peut aider à rendre la pagination plus fluide dans les ensembles de données dynamiques.
  • Stockage des points de contrôle : Pour récupérer de grands volumes de données, envisagez d’enregistrer un point 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, en fonction des options de pagination de la Management API d’Auth0.

​
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 de la Management API à des fins de test.