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.
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 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; 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:
{
"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
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"}'
keenauth connections test conn_01j9xp6q0r1s5t7v9w1x3y5z7b --return-url https://admin.example.com/sso/test-done