Migrar el host SP de una conexión

POST /v1/connections/{connection_id}:migrate-sp-host · permiso connections:write

Inicia el traslado de los endpoints SP (ACS, metadatos, cierre de sesión único y callback de OIDC) de una conexión empresarial a un nuevo host, por ejemplo del host keenauth.app a su dominio personalizado verificado. De lo contrario, las URL del SP están congeladas, porque el proveedor de identidad las tiene registradas.

La solicitud crea un borrador de revisión de tipo sp_host, sea cual sea el estado de la conexión. Por ahora no cambia nada para los inicios de sesión:

  1. Descargue los nuevos metadatos del SP con Descargar los metadatos del SP y revision_id, y entréguelos al administrador del proveedor de identidad. El nuevo host ya sirve estos metadatos y la prueba de inicio de sesión del borrador, nada más.
  2. Pruebe el borrador con Probar una conexión y revision_id.
  3. Publique la revisión. La conexión ahora usa el nuevo host. El host anterior sigue respondiendo durante 30 días más para que el proveedor de identidad pueda actualizarse; después devuelve 404.

Un nuevo borrador descarta el borrador anterior de la conexión. La solicitud se audita como connection.revision_created.

Solicitud

Campo Tipo Obligatorio Descripción
connection_id ruta sí ID de la conexión empresarial (conn_…).
Idempotency-Key cabecera no Clave opcional que hace segura la reintentación de una solicitud (de 16 a 64 caracteres).
sp_host cadena sí El nuevo host: un host activo de este entorno (su host keenauth.app o un dominio personalizado verificado), en minúsculas y sin puerto.

Respuesta

200 OK con el borrador de revisión:

{
  "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": null
}

superseded_revision_id es el borrador anterior que esta solicitud descartó, si lo hubo.

Errores

HTTP code Cuándo
400 unknown_field El cuerpo contiene un campo desconocido.
401 unauthenticated La credencial falta, no es válida o fue revocada.
403 insufficient_permissions La credencial no tiene connections:write.
404 not_found La conexión no existe en este entorno o no es una conexión empresarial.
409 conflict La ventana de 30 días de la migración anterior del host SP todavía está abierta, o la conexión aún no tiene configuración de protocolo.
422 validation_failed errors[] apunta a /sp_host con required, invalid_value (no es un nombre de host en minúsculas), not_in_environment (no es un host activo de este entorno) o unchanged (ya es el host SP de la conexión).
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:migrate-sp-host" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"sp_host":"login.example.com"}'

keenauth connections migrate-sp-host conn_01j9xp6q0r1s5t7v9w1x3y5z7b --sp-host login.example.com --yes