# Listar las revisiones de una conexión

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

Lista las revisiones de una conexión empresarial (SAML u OIDC), de la más reciente a la más antigua: el borrador pendiente (como máximo uno) y las revisiones publicadas o descartadas en los últimos 90 días.

En una conexión **activa**, un cambio crítico para la seguridad no se aplica directamente. Se convierte en una **revisión en borrador** y la configuración activa se mantiene tal cual hasta que pruebe y publique el borrador:

- importar metadatos de SAML que cambien el ID de entidad o la URL de SSO del proveedor de identidad, o que eliminen un anclaje de firma ([Importar metadatos](import-metadata.md));
- cambiar el `issuer` o el `client_id` de OIDC ([Establecer la configuración de OIDC](../connection-oidc/put.md));
- cada migración del host del SP, sea cual sea el estado de la conexión ([Migrar el host del SP](migrate-sp-host.md)).

Pruebe un borrador con [Probar una conexión](test.md) y su `revision_id`, y luego [publíquelo](publish-revision.md). Un borrador nuevo descarta el anterior (`discard_reason: superseded`).

Una revisión muestra solo los nuevos valores no secretos (`changes`). Un nuevo secreto de cliente OIDC aparece únicamente como `client_secret_change` (`keep`, `replace` o `clear`); el secreto y sus últimos caracteres nunca se devuelven. Quién creó o aprobó una revisión queda registrado en el registro de auditoría de gestión (`connection.revision_created`, `connection.revision_published`), no aquí.

## Solicitud

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `connection_id` | ruta | sí | ID de la conexión empresarial (`conn_…`). |
| `limit` | consulta | no | Tamaño de página, de 1 a 100 (por defecto 20). |
| `after` | consulta | no | Cursor de `list_metadata.after`. Un cursor solo funciona para la conexión que lo generó. |

La lista se pagina solo hacia delante: `before` y `order` no se admiten (`422`).

## Respuesta

`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 | Descripción |
|---|---|
| `kind` | `configuration` (cambio del proveedor de identidad o del cliente OIDC) o `sp_host` (migración del host del SP). |
| `status` | `draft` (pendiente de prueba y publicación), `published` o `discarded`. |
| `decided_at` / `purge_after` | Cuándo se publicó o descartó la revisión, y cuándo se elimina (90 días después); `null` para un borrador. |
| `changes` | Los nuevos valores. Los campos que la revisión no modifica son `null`. |
| `latest_test` | La última prueba de inicio de sesión de esta revisión de las últimas 24 horas, o `null`. Para publicar se necesita una prueba `passed`. |

## Errores

| HTTP | code | Cuándo |
|---|---|---|
| 400 | `invalid_cursor` | El cursor está mal formado o pertenece a otra conexión o consulta. |
| 401 | `unauthenticated` | La credencial falta, no es válida o ha sido revocada. |
| 403 | `insufficient_permissions` | La credencial no tiene `connections:read`. |
| 404 | `not_found` | La conexión no existe en este entorno o no es una conexión empresarial. |
| 422 | `validation_failed` | Un parámetro de consulta no es válido (por ejemplo, `limit` superior a 100, o `before`). |
| 429 | `rate_limited` | Se superó el límite de tasa; reintente después del período indicado en `Retry-After`. |
| 503 | `service_unavailable` | Una dependencia no está disponible temporalmente; reintente después del período indicado en `Retry-After`. |

## Ejemplo

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