Collection Postman et document OpenAPI

KeenAuth publie son contrat d'API lisible par machine sous forme de deux fichiers. Les deux sont générés à partir de la définition publique de l'API de gestion à chaque version, de sorte qu'ils correspondent toujours à la référence de l'API. Les opérations internes n'y figurent jamais.

Fichier Format Téléchargement
Collection Postman Postman Collection v2.1.0 postman_collection.json
Document OpenAPI OpenAPI 3.1 openapi.json

Importer dans Postman

  1. Dans Postman, choisissez Import et sélectionnez le fichier postman_collection.json téléchargé.
  2. Ouvrez les variables de la collection et définissez apiKey avec une clé de l'API de gestion. Créez-en une dans le tableau de bord ou avec la CLI ; la clé est envoyée sous forme de jeton Bearer.
  3. Définissez region avec la région de votre environnement (eu par défaut). Les requêtes sont envoyées à l'hôte api.{{region}}.keenauth.com, chemin /v1.
  4. Envoyez une requête. Chaque requête POST porte un en-tête Idempotency-Key que Postman remplit avec un GUID neuf, de sorte qu'une requête relancée reste sûre.

Les requêtes sont regroupées dans un dossier par tag d'API. Les paramètres de chemin comme {{user_id}} sont des variables de collection : définissez-les avant d'envoyer une requête qui en a besoin.

Utiliser le document OpenAPI

Le document OpenAPI sert d'entrée à la génération de code et aux passerelles d'API, linters et serveurs de simulation. Le même document est servi par l'API elle-même à l'adresse https://api.eu.keenauth.com/v1/openapi.json.

Archive du contrat et empreintes des SDK

Le document OpenAPI est aussi publié à un chemin d'archive adressé par son contenu. Le segment de chemin est le SHA-256 des octets du document, de sorte que le fichier situé à un chemin d'archive ne change jamais :

Fichier Contenu
/openapi/<sha256>/openapi.json Le document, identique octet par octet à /api/openapi.json de cette version
/openapi/<sha256>/openapi.json.sha256 L'empreinte au format sha256sum
/openapi/index.json Les documents archivés : sha256, info_version, path ; current marque le plus récent

Chaque SDK serveur enregistre l'empreinte du document à partir duquel il a été généré :

SDK Emplacement
Node.js (@keenauth/node) Export OPENAPI_SHA256 et keenauth.openapiSha256 dans package.json
Python (keenauth-python) keenauth.OPENAPI_SHA256 et l'URL de projet OpenAPI document dans les métadonnées du paquet
Go keenauth.OpenAPISHA256

Pour vérifier un téléchargement, exécutez sha256sum -c openapi.json.sha256 dans le dossier qui contient les deux fichiers. Comparez l'empreinte à la valeur indiquée par votre SDK pour savoir avec quelle version de l'API le SDK a été construit.