# Collezione Postman e documento OpenAPI

KeenAuth pubblica il proprio contratto API leggibile dalle macchine in due file. Entrambi sono generati dalla definizione pubblica dell'API di gestione a ogni rilascio, quindi corrispondono sempre al riferimento API. Le operazioni interne non compaiono mai in essi.

| File | Formato | Download |
|---|---|---|
| Collezione Postman | Postman Collection v2.1.0 | [postman_collection.json](/api/postman_collection.json) |
| Documento OpenAPI | OpenAPI 3.1 | [openapi.json](/api/openapi.json) |

## Importare in Postman

1. In Postman, scegli **Import** e seleziona il file `postman_collection.json` scaricato.
2. Apri le variabili della collezione e imposta `apiKey` con una chiave dell'API di gestione. Creala nella dashboard o con la CLI; la chiave viene inviata come token Bearer.
3. Imposta `region` sulla regione del tuo ambiente (`eu` è il valore predefinito). Le richieste vanno all'host `api.{{region}}.keenauth.com`, percorso `/v1`.
4. Invia una richiesta. Ogni richiesta `POST` include un header `Idempotency-Key` che Postman compila con un nuovo GUID, quindi una richiesta ritentata è sicura.

Le richieste sono raggruppate in una cartella per ogni tag API. I parametri di percorso come `{{user_id}}` sono variabili della collezione: impostali prima di inviare una richiesta che li richiede.

## Usare il documento OpenAPI

Il documento OpenAPI è l'input per la generazione del codice e per API gateway, linter e mock server. Lo stesso documento è servito dall'API stessa all'indirizzo `https://api.eu.keenauth.com/v1/openapi.json`.

## Archivio del contratto e digest degli SDK

Il documento OpenAPI è pubblicato anche in un percorso di archivio indirizzato dal contenuto. Il segmento del percorso è il SHA-256 dei byte del documento, quindi il file in un percorso di archivio non cambia mai:

| File | Contenuto |
|---|---|
| `/openapi/<sha256>/openapi.json` | Il documento, identico byte per byte a `/api/openapi.json` di quella versione |
| `/openapi/<sha256>/openapi.json.sha256` | Il digest nel formato `sha256sum` |
| [`/openapi/index.json`](/openapi/index.json) | I documenti archiviati: `sha256`, `info_version`, `path`; `current` indica l'ultimo |

Ogni SDK server registra il digest del documento da cui è stato generato:

| SDK | Dove |
|---|---|
| Node.js (`@keenauth/node`) | Export `OPENAPI_SHA256` e `keenauth.openapiSha256` in `package.json` |
| Python (`keenauth-python`) | `keenauth.OPENAPI_SHA256` e l'URL di progetto `OpenAPI document` nei metadati del pacchetto |
| Go | `keenauth.OpenAPISHA256` |

Per verificare un download, esegui `sha256sum -c openapi.json.sha256` nella cartella che contiene entrambi i file. Confronta il digest con il valore riportato dal tuo SDK per capire con quale versione dell'API è stato compilato.