# Lister les révisions d'une connexion

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

Liste les révisions d'une connexion d'entreprise (SAML ou OIDC), de la plus récente à la plus ancienne : le brouillon en attente (au plus un) et les révisions publiées ou abandonnées au cours des 90 derniers jours.

Sur une connexion **active**, une modification critique pour la sécurité n'est pas appliquée directement. Elle devient une **révision en brouillon** et la configuration en production reste inchangée tant que vous n'avez pas testé et publié le brouillon :

- l'importation de métadonnées SAML qui modifie l'ID d'entité ou l'URL SSO du fournisseur d'identité, ou qui supprime une épingle de signature ([Importer les métadonnées](import-metadata.md)) ;
- la modification de l'`issuer` ou du `client_id` OIDC ([Mettre à jour la configuration OIDC](../connection-oidc/put.md)) ;
- toute migration de l'hôte SP, quel que soit le statut de la connexion ([Migrer l'hôte SP](migrate-sp-host.md)).

Testez un brouillon avec [Tester une connexion](test.md) et son `revision_id`, puis [publiez-le](publish-revision.md). Un nouveau brouillon remplace le précédent (`discard_reason: superseded`).

Une révision n'affiche que les nouvelles valeurs non secrètes (`changes`). Un nouveau secret client OIDC n'apparaît que sous la forme `client_secret_change` (`keep`, `replace` ou `clear`) ; le secret et ses derniers caractères ne sont jamais renvoyés. Qui a créé ou décidé une révision est consigné dans le journal d'audit de gestion (`connection.revision_created`, `connection.revision_published`), et non ici.

## Requête

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `connection_id` | chemin | oui | ID de la connexion d'entreprise (`conn_…`). |
| `limit` | requête | non | Taille de page, de 1 à 100 (20 par défaut). |
| `after` | requête | non | Curseur issu de `list_metadata.after`. Un curseur ne fonctionne que pour la connexion qui l'a produit. |

La liste ne se parcourt que vers l'avant : `before` et `order` ne sont pas pris en charge (`422`).

## Réponse

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

| Champ | Description |
|---|---|
| `kind` | `configuration` (modification du fournisseur d'identité ou du client OIDC) ou `sp_host` (migration de l'hôte SP). |
| `status` | `draft` (en attente de test et de publication), `published` ou `discarded`. |
| `decided_at` / `purge_after` | Date de publication ou d'abandon de la révision, et date de suppression (90 jours plus tard) ; `null` pour un brouillon. |
| `changes` | Les nouvelles valeurs. Les champs que la révision ne modifie pas valent `null`. |
| `latest_test` | Le dernier test de connexion de cette révision effectué au cours des 24 dernières heures, ou `null`. La publication nécessite un test `passed`. |

## Erreurs

| HTTP | code | Cas |
|---|---|---|
| 400 | `invalid_cursor` | Le curseur est mal formé ou appartient à une autre connexion ou à une autre requête. |
| 401 | `unauthenticated` | L'identifiant est absent, invalide ou révoqué. |
| 403 | `insufficient_permissions` | L'identifiant ne dispose pas de `connections:read`. |
| 404 | `not_found` | La connexion n'existe pas dans cet environnement ou n'est pas une connexion d'entreprise. |
| 422 | `validation_failed` | Un paramètre de requête est invalide (par exemple `limit` supérieur à 100, ou `before`). |
| 429 | `rate_limited` | La limite de débit a été dépassée ; réessayez après la durée indiquée par `Retry-After`. |
| 503 | `service_unavailable` | Une dépendance est temporairement indisponible ; réessayez après la durée indiquée par `Retry-After`. |

## Exemple

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