# Migra l'host SP di una connessione

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

Avvia lo spostamento degli endpoint SP (ACS, metadati, single logout, callback OIDC) di una connessione enterprise su un nuovo host, per esempio dall'host `keenauth.app` al tuo dominio personalizzato verificato. Altrimenti gli URL SP sono bloccati, perché il provider di identità li ha già.

La richiesta crea una **bozza di revisione** di tipo `sp_host`, indipendentemente dallo stato della connessione. Per ora non cambia nulla per gli accessi:

1. Scarica i nuovi metadati SP con [Scarica i metadati SP](sp-metadata.md) e `revision_id`, e consegnali all'amministratore del provider di identità. Il nuovo host serve già questi metadati e l'accesso di test della bozza, nient'altro.
2. Testa la bozza con [Testa una connessione](test.md) e `revision_id`.
3. [Pubblica la revisione](publish-revision.md). La connessione ora usa il nuovo host. Il vecchio host continua a rispondere per altri 30 giorni così il provider di identità può essere aggiornato, poi restituisce `404`.

Una nuova bozza scarta la bozza precedente della connessione. La richiesta viene registrata in audit come `connection.revision_created`.

## Richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `connection_id` | path | sì | ID della connessione enterprise (`conn_…`). |
| `Idempotency-Key` | header | no | Chiave facoltativa che rende sicuro ripetere una richiesta (16-64 caratteri). |
| `sp_host` | string | sì | Il nuovo host: un host attivo di questo ambiente (il suo host `keenauth.app` o un dominio personalizzato verificato), in minuscolo, senza porta. |

## Risposta

`200 OK` con la bozza di revisione:

```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` è la bozza precedente scartata da questa richiesta, se presente.

## Errori

| HTTP | code | Quando |
|---|---|---|
| 400 | `unknown_field` | Il corpo contiene un campo sconosciuto. |
| 401 | `unauthenticated` | La credenziale è mancante, non valida o revocata. |
| 403 | `insufficient_permissions` | La credenziale non ha `connections:write`. |
| 404 | `not_found` | La connessione non esiste in questo ambiente o non è una connessione enterprise. |
| 409 | `conflict` | La finestra di 30 giorni della precedente migrazione dell'host SP è ancora aperta, oppure la connessione non ha ancora una configurazione del protocollo. |
| 422 | `validation_failed` | `errors[]` indica `/sp_host` con `required`, `invalid_value` (non è un nome host in minuscolo), `not_in_environment` (non è un host attivo di questo ambiente) o `unchanged` (è già l'host SP della connessione). |
| 429 | `rate_limited` | È stato superato il limite di richieste; riprova dopo il periodo indicato in `Retry-After`. |
| 503 | `service_unavailable` | Una dipendenza è temporaneamente non disponibile; riprova dopo il periodo indicato in `Retry-After`. |

## Esempio

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