# Elenca le revisioni di una connessione

`GET /v1/connections/{connection_id}/revisions` · autorizzazione `connections:read`

Elenca le revisioni di una connessione enterprise (SAML o OIDC), dalla più recente: la bozza in attesa (al massimo una) e le revisioni pubblicate o scartate negli ultimi 90 giorni.

Su una connessione **attiva**, una modifica critica per la sicurezza non viene applicata direttamente. Diventa una **revisione in bozza** e la configurazione attiva resta invariata finché non testi e pubblichi la bozza:

- importare metadati SAML che modificano l'entity ID o l'URL SSO del provider di identità, oppure rimuovono un pin di firma ([Importa i metadati](import-metadata.md));
- modificare l'`issuer` o il `client_id` OIDC ([Imposta la configurazione OIDC](../connection-oidc/put.md));
- ogni migrazione dell'host SP, indipendentemente dallo stato della connessione ([Migra l'host SP](migrate-sp-host.md)).

Testa una bozza con [Testa una connessione](test.md) e il suo `revision_id`, poi [pubblicala](publish-revision.md). Una nuova bozza scarta la precedente (`discard_reason: superseded`).

Una revisione mostra solo i nuovi valori non segreti (`changes`). Un nuovo client secret OIDC compare solo come `client_secret_change` (`keep`, `replace` o `clear`); il secret e i suoi ultimi caratteri non vengono mai restituiti. Chi ha creato o deciso una revisione è registrato nel log di audit di gestione (`connection.revision_created`, `connection.revision_published`), non qui.

## Richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `connection_id` | path | sì | ID della connessione enterprise (`conn_…`). |
| `limit` | query | no | Dimensione della pagina, da 1 a 100 (predefinito 20). |
| `after` | query | no | Cursore da `list_metadata.after`. Il cursore funziona solo per la connessione che l'ha prodotto. |

L'elenco è paginato solo in avanti: `before` e `order` non sono supportati (`422`).

## Risposta

`200 OK`:

```json
{
  "data": [
    {
      "id": "connrev_01j9xr8c2d4e6f8g0h2j4k6m8n",
      "connection_id": "conn_01j9xp6q0r1s5t7v9w1x3y5z7b",
      "protocol": "saml",
      "kind": "sp_host",
      "status": "draft",
      "discard_reason": null,
      "created_at": "2026-10-28T10:00:00Z",
      "decided_at": null,
      "purge_after": null,
      "superseded_revision_id": null,
      "changes": {
        "sp_host": "login.example.com",
        "idp_entity_id": null,
        "idp_sso_url": null,
        "idp_slo_url": null,
        "certificate_fingerprints": [],
        "mfa_authn_context_values": null,
        "issuer": null,
        "client_id": null,
        "client_auth_method": null,
        "provider_profile": null,
        "client_secret_change": null
      },
      "latest_test": {
        "test_id": "conntest_01j9xr4a6b8c0d2e4f6g8h0j2k",
        "status": "passed",
        "failure_reason": null,
        "started_at": "2026-10-28T10:05:00Z",
        "completed_at": "2026-10-28T10:06:00Z"
      }
    }
  ],
  "list_metadata": { "before": null, "after": null }
}
```

| Campo | Descrizione |
|---|---|
| `kind` | `configuration` (modifica del provider di identità o del client OIDC) oppure `sp_host` (migrazione dell'host SP). |
| `status` | `draft` (in attesa di test e pubblicazione), `published` oppure `discarded`. |
| `decided_at` / `purge_after` | Quando la revisione è stata pubblicata o scartata, e quando viene eliminata (90 giorni dopo); `null` per una bozza. |
| `changes` | I nuovi valori. I campi che la revisione non modifica sono `null`. |
| `latest_test` | L'ultimo test di accesso di questa revisione nelle ultime 24 ore, oppure `null`. La pubblicazione richiede un test `passed`. |

## Errori

| HTTP | code | Quando |
|---|---|---|
| 400 | `invalid_cursor` | Il cursore è malformato oppure appartiene a un'altra connessione o a un'altra query. |
| 401 | `unauthenticated` | La credenziale manca, non è valida o è stata revocata. |
| 403 | `insufficient_permissions` | La credenziale non ha `connections:read`. |
| 404 | `not_found` | La connessione non esiste in questo ambiente oppure non è una connessione enterprise. |
| 422 | `validation_failed` | Un parametro di query non è valido (ad esempio `limit` superiore a 100, oppure `before`). |
| 429 | `rate_limited` | È stato superato il limite di richieste; riprova dopo il periodo indicato in `Retry-After`. |
| 503 | `service_unavailable` | Una dipendenza non è disponibile temporaneamente; riprova dopo il periodo indicato in `Retry-After`. |

## Esempio

```bash
curl "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/revisions?limit=20" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

```bash
keenauth connections revisions list conn_01j9xp6q0r1s5t7v9w1x3y5z7b --limit 20
```