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 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 e revision_id.
  3. Pubblica la revisione. 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:

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

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