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 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 und revision_id.
  3. Veröffentlichen Sie die Revision. 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:

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

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