# 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](sp-metadata.md) 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](test.md) y `revision_id`.
3. [Publique la revisión](publish-revision.md). 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:

```json
{
  "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

```bash
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"}'
```

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