# Revisionen einer Verbindung auflisten

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

Listet die Revisionen einer Enterprise-Verbindung (SAML oder OIDC) auf, neueste zuerst: den ausstehenden Entwurf (höchstens einen) sowie die in den letzten 90 Tagen veröffentlichten oder verworfenen Revisionen.

Bei einer **aktiven** Verbindung wird eine sicherheitskritische Änderung nicht direkt angewendet. Sie wird zu einer **Entwurfsrevision**, und die aktive Konfiguration bleibt unverändert, bis Sie den Entwurf testen und veröffentlichen:

- Import von SAML-Metadaten, die die Entity-ID oder die SSO-URL des Identitätsanbieters ändern oder einen Signatur-Pin entfernen ([Metadaten importieren](import-metadata.md));
- Änderung von `issuer` oder `client_id` der OIDC-Konfiguration ([OIDC-Konfiguration setzen](../connection-oidc/put.md));
- jede Migration des SP-Hosts, unabhängig vom Status der Verbindung ([SP-Host migrieren](migrate-sp-host.md)).

Testen Sie einen Entwurf mit [Eine Verbindung testen](test.md) und dessen `revision_id` und veröffentlichen Sie ihn anschließend [über die Veröffentlichung der Revision](publish-revision.md). Ein neuer Entwurf verwirft den vorherigen (`discard_reason: superseded`).

Eine Revision zeigt nur die neuen, nicht geheimen Werte (`changes`). Ein neues OIDC-Client-Secret erscheint nur als `client_secret_change` (`keep`, `replace` oder `clear`); das Secret und seine letzten Zeichen werden nie zurückgegeben. Wer eine Revision erstellt oder entschieden hat, wird im Verwaltungs-Auditprotokoll erfasst (`connection.revision_created`, `connection.revision_published`), nicht hier.

## Anfrage

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `connection_id` | Pfad | ja | ID der Enterprise-Verbindung (`conn_…`). |
| `limit` | Query | nein | Seitengröße, 1–100 (Standard 20). |
| `after` | Query | nein | Cursor aus `list_metadata.after`. Ein Cursor funktioniert nur für die Verbindung, die ihn erzeugt hat. |

Die Liste wird nur vorwärts paginiert: `before` und `order` werden nicht unterstützt (`422`).

## Antwort

`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 }
}
```

| Feld | Beschreibung |
|---|---|
| `kind` | `configuration` (Änderung des Identitätsanbieters oder des OIDC-Clients) oder `sp_host` (Migration des SP-Hosts). |
| `status` | `draft` (wartet auf Test und Veröffentlichung), `published` oder `discarded`. |
| `decided_at` / `purge_after` | Wann die Revision veröffentlicht oder verworfen wurde und wann sie gelöscht wird (90 Tage später); bei einem Entwurf `null`. |
| `changes` | Die neuen Werte. Felder, die die Revision nicht ändert, sind `null`. |
| `latest_test` | Der letzte Test-Login dieser Revision aus den letzten 24 Stunden, oder `null`. Für die Veröffentlichung ist ein `passed`-Test erforderlich. |

## Fehler

| HTTP | code | Wann |
|---|---|---|
| 400 | `invalid_cursor` | Der Cursor ist fehlerhaft oder gehört zu einer anderen Verbindung oder Abfrage. |
| 401 | `unauthenticated` | Die Anmeldeinformation fehlt, ist ungültig oder widerrufen. |
| 403 | `insufficient_permissions` | Die Anmeldeinformation besitzt nicht `connections:read`. |
| 404 | `not_found` | Die Verbindung existiert in dieser Umgebung nicht oder ist keine Enterprise-Verbindung. |
| 422 | `validation_failed` | Ein Query-Parameter ist ungültig (etwa `limit` über 100 oder `before`). |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach dem Zeitraum aus `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach dem Zeitraum aus `Retry-After`. |

## Beispiel

```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
```