# 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](/api/postman_collection.json) |
| Document OpenAPI | OpenAPI 3.1 | [openapi.json](/api/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`](/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.