# Postman-Collection und OpenAPI-Dokument

KeenAuth veröffentlicht seinen maschinenlesbaren API-Vertrag als zwei Dateien. Beide werden bei jedem Release aus der öffentlichen Definition der Management-API erzeugt und stimmen daher immer mit der API-Referenz überein. Interne Operationen erscheinen darin nie.

| Datei | Format | Download |
|---|---|---|
| Postman-Collection | Postman Collection v2.1.0 | [postman_collection.json](/api/postman_collection.json) |
| OpenAPI-Dokument | OpenAPI 3.1 | [openapi.json](/api/openapi.json) |

## In Postman importieren

1. Wählen Sie in Postman **Import** und wählen Sie die heruntergeladene `postman_collection.json`.
2. Öffnen Sie die Collection-Variablen und setzen Sie `apiKey` auf einen Management-API-Schlüssel. Erstellen Sie einen im Dashboard oder mit der CLI; der Schlüssel wird als Bearer-Token gesendet.
3. Setzen Sie `region` auf die Region Ihrer Umgebung (`eu` ist der Standard). Anfragen gehen an den Host `api.{{region}}.keenauth.com`, Pfad `/v1`.
4. Senden Sie eine Anfrage. Jede `POST`-Anfrage trägt einen `Idempotency-Key`-Header, den Postman mit einer neuen GUID füllt, sodass eine wiederholte Anfrage sicher ist.

Anfragen sind in einem Ordner pro API-Tag gruppiert. Pfadparameter wie `{{user_id}}` sind Collection-Variablen: Setzen Sie sie, bevor Sie eine Anfrage senden, die sie benötigt.

## OpenAPI-Dokument verwenden

Das OpenAPI-Dokument dient als Eingabe für die Codegenerierung sowie für API-Gateways, Linter und Mock-Server. Dasselbe Dokument stellt die API selbst unter `https://api.eu.keenauth.com/v1/openapi.json` bereit.

## Vertragsarchiv und SDK-Prüfsummen

Das OpenAPI-Dokument wird außerdem unter einem inhaltsadressierten Archivpfad veröffentlicht. Das Pfadsegment ist der SHA-256-Wert der Dokumentbytes, daher ändert sich die Datei unter einem Archivpfad nie:

| Datei | Inhalt |
|---|---|
| `/openapi/<sha256>/openapi.json` | Das Dokument, byte-identisch mit `/api/openapi.json` dieser Version |
| `/openapi/<sha256>/openapi.json.sha256` | Die Prüfsumme im `sha256sum`-Format |
| [`/openapi/index.json`](/openapi/index.json) | Die archivierten Dokumente: `sha256`, `info_version`, `path`; `current` markiert das neueste |

Jedes Server-SDK speichert die Prüfsumme des Dokuments, aus dem es erzeugt wurde:

| SDK | Wo |
|---|---|
| Node.js (`@keenauth/node`) | Export `OPENAPI_SHA256` und `keenauth.openapiSha256` in `package.json` |
| Python (`keenauth-python`) | `keenauth.OPENAPI_SHA256` und die Projekt-URL `OpenAPI document` in den Paketmetadaten |
| Go | `keenauth.OpenAPISHA256` |

Um einen Download zu prüfen, führen Sie `sha256sum -c openapi.json.sha256` in dem Ordner aus, der beide Dateien enthält. Vergleichen Sie die Prüfsumme mit dem Wert, den Ihr SDK meldet, um zu sehen, gegen welche API-Version das SDK erstellt wurde.