# SP-Host einer Verbindung migrieren

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

Startet die Verschiebung der SP-Endpunkte (ACS, Metadaten, Single Logout, OIDC-Callback) einer Enterprise-Verbindung auf einen neuen Host, zum Beispiel vom Host `keenauth.app` auf Ihre verifizierte Custom Domain. Die SP-URLs sind sonst festgelegt, weil der Identitätsanbieter sie kennt.

Die Anfrage erstellt eine **Entwurfsrevision** vom Typ `sp_host`, unabhängig vom Status der Verbindung. Für Anmeldungen ändert sich zunächst nichts:

1. Laden Sie die neuen SP-Metadaten mit [SP-Metadaten herunterladen](sp-metadata.md) und `revision_id` herunter und geben Sie sie an den Administrator des Identitätsanbieters weiter. Der neue Host liefert diese Metadaten und die Test-Anmeldung des Entwurfs, sonst nichts.
2. Testen Sie den Entwurf mit [Verbindung testen](test.md) und `revision_id`.
3. [Veröffentlichen Sie die Revision](publish-revision.md). Die Verbindung verwendet nun den neuen Host. Der alte Host antwortet noch 30 weitere Tage, damit der Identitätsanbieter aktualisiert werden kann, und liefert danach `404`.

Ein neuer Entwurf verwirft den bisherigen Entwurf der Verbindung. Die Anfrage wird als `connection.revision_created` auditiert.

## Anfrage

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `connection_id` | Pfad | ja | ID der Enterprise-Verbindung (`conn_…`). |
| `Idempotency-Key` | Header | nein | Optionaler Schlüssel, der eine wiederholte Anfrage sicher macht (16–64 Zeichen). |
| `sp_host` | string | ja | Der neue Host: ein aktiver Host dieser Umgebung (ihr Host `keenauth.app` oder eine verifizierte Custom Domain), in Kleinbuchstaben, ohne Port. |

## Antwort

`200 OK` mit der Entwurfsrevision:

```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` ist der bisherige Entwurf, den diese Anfrage verworfen hat, falls vorhanden.

## Fehler

| HTTP | code | Wann |
|---|---|---|
| 400 | `unknown_field` | Der Anfragetext enthält ein unbekanntes Feld. |
| 401 | `unauthenticated` | Die Anmeldedaten fehlen, sind ungültig oder widerrufen. |
| 403 | `insufficient_permissions` | Die Anmeldedaten haben nicht `connections:write`. |
| 404 | `not_found` | Die Verbindung existiert in dieser Umgebung nicht oder ist keine Enterprise-Verbindung. |
| 409 | `conflict` | Das 30-Tage-Fenster der vorherigen SP-Host-Migration ist noch offen oder die Verbindung hat noch keine Protokollkonfiguration. |
| 422 | `validation_failed` | `errors[]` verweist auf `/sp_host` mit `required`, `invalid_value` (kein Hostname in Kleinbuchstaben), `not_in_environment` (kein aktiver Host dieser Umgebung) oder `unchanged` (ist bereits der SP-Host der Verbindung). |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Zeit aus `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach der Zeit aus `Retry-After`. |

## Beispiel

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