# Probar una conexión

`POST /v1/connections/{connection_id}:test` · permiso `connections:write`

Inicia un inicio de sesión de prueba con la configuración actual de una conexión empresarial y devuelve una URL de prueba. La persona que configura la conexión abre la URL en un navegador e inicia sesión en el proveedor de identidad. Después, el navegador regresa a `return_url` con el parámetro de consulta `test_id`. Consulte el resultado con [Obtener el resultado de la prueba más reciente](latest-test-result.md).

Un inicio de sesión de prueba no crea ninguna sesión, no aprovisiona ningún usuario y no vincula ninguna cuenta. Para activar la conexión es necesaria una prueba superada; si se cambia la configuración del proveedor de identidad, la prueba deja de ser válida.

Para probar una [revisión en borrador](revisions.md) en lugar de la configuración activa, envíe su `revision_id`. El borrador se superpone a la configuración activa solo para esta prueba (en una migración de host de SP, la URL de prueba está en el nuevo host). Una prueba superada de una revisión es la evidencia que necesita [Publicar una revisión](publish-revision.md); no cuenta como evidencia de activación de la configuración activa.

La `test_url` es un enlace de portador: cualquiera que la tenga puede ejecutar la prueba durante 10 minutos, una sola vez. Solo se devuelve en esta respuesta (`Cache-Control: no-store`) y nunca se registra ni se audita. Si repite la solicitud con el mismo `Idempotency-Key`, la respuesta reproducida no tiene `test_url` y contiene `secret_redacted: true`; en ese caso, inicie una nueva prueba. Los inicios se auditan como `connection.test_started` solo con el ID de la prueba.

## Solicitud

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `connection_id` | path | sí | ID de la conexión empresarial (`conn_…`). |
| `return_url` | string | sí | URL absoluta `https` a la que regresa el navegador tras la prueba, de como máximo 2048 bytes. Se añade `test_id` como parámetro de consulta. |
| `revision_id` | string | no | Una revisión en borrador de la conexión (`connrev_…`) que se probará en lugar de la configuración activa. |

## Respuesta

`200 OK`:

```json
{
  "test_id": "conntest_01j9xr4a6b8c0d2e4f6g8h0j2k",
  "test_url": "https://acme.eu1.keenauth.app/sso/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/start?t=…",
  "expires_at": "2026-10-20T10:10:00Z"
}
```

| Campo | Descripción |
|---|---|
| `test_id` | ID de la prueba (`conntest_…`). |
| `test_url` | URL que se abre en el navegador; válida durante 10 minutos y de un solo uso. No la comparta ni la registre. Ausente en una respuesta reproducida. |
| `expires_at` | Cuándo caduca la URL de prueba. |
| `secret_redacted` | `true` en una respuesta reproducida con el mismo `Idempotency-Key`. |

## Errores

| HTTP | código | Cuándo |
|---|---|---|
| 404 | `not_found` | La conexión no existe en este entorno o no es una conexión empresarial. |
| 409 | `conflict` | La conexión todavía no puede probarse (no tiene configuración de protocolo). |
| 422 | `validation_failed` | `return_url` falta o no es una URL absoluta `https` (`errors[]` apunta a `/return_url`), o `revision_id` está mal formado (`invalid_value`) o no es una revisión en borrador de esta conexión (`not_found`; puntero `/revision_id`). |
| 400 | `unknown_field` | El cuerpo tiene un campo desconocido. |
| 401 | `unauthenticated` | Falta la credencial, no es válida o fue revocada. |
| 403 | `insufficient_permissions` | La credencial no tiene el permiso requerido. |
| 429 | `rate_limited` | Se superó el límite de frecuencia; reintente después del periodo indicado en `Retry-After`. |
| 503 | `service_unavailable` | Una dependencia no está disponible temporalmente; reintente después del periodo indicado en `Retry-After`. |

## Ejemplo

```bash
curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b:test" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"return_url":"https://admin.example.com/sso/test-done"}'
```

```bash
keenauth connections test conn_01j9xp6q0r1s5t7v9w1x3y5z7b --return-url https://admin.example.com/sso/test-done
```