Benutzerdefinierte Domäne zur primären machen

POST /v1/custom-domains/{custom_domain_id}:make-primary · Berechtigung custom-domains:write

Macht die Domäne zur primären benutzerdefinierten Domäne der Umgebung (gehostete Anmeldelinks verwenden sie); die bisherige primäre Domäne verliert diese Rolle im selben Vorgang. Die Domäne muss active sein; die bereits primäre Domäne erneut zur primären zu machen ändert nichts. Liegt der Issuer der Umgebung auf einer benutzerdefinierten Domäne, ändert ein Wechsel der primären Domäne den Issuer und muss als Issuer-Migration geplant werden.

Anfrage

Feld Typ Erforderlich Beschreibung
custom_domain_id string ja ID der benutzerdefinierten Domäne (cdom_…).
Idempotency-Key header nein Optionaler Schlüssel (16–64 Zeichen), der einen wiederholten Request sicher macht.
If-Match header nein Optional. Wenn angegeben, muss es mit dem ETag der Domäne übereinstimmen (sonst 412).

Kein Request-Body.

Antwort

200 OK mit der Domäne und einem ETag-Header.

{
  "id": "cdom_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "hostname": "login.example.com",
  "is_primary": true,
  "status": "active",
  "failure_reason": null,
  "dns_records": [
    {
      "type": "TXT",
      "name": "_akp-verify.login.example.com",
      "value": "idp-verify=3q2-7wEXAMPLEtokenQ9"
    },
    {
      "type": "CNAME",
      "name": "login.example.com",
      "value": "acme.eu.edge.keenauth.app"
    }
  ],
  "certificate_expires_at": "2027-01-04T09:31:12Z",
  "last_checked_at": "2026-10-05T09:31:00Z",
  "next_check_at": null,
  "activated_at": "2026-10-05T09:31:12Z",
  "degraded_since": null,
  "status_changed_at": "2026-10-05T09:31:12Z",
  "created_at": "2026-10-05T09:30:00.123456Z",
  "updated_at": "2026-10-05T09:31:12Z"
}

Fehler

HTTP Code Wann
404 not_found Die benutzerdefinierte Domäne existiert nicht oder gehört zu einer anderen Umgebung.
409 custom_domain_state_conflict Die Domäne ist nicht active.
409 issuer_change_requires_schedule Der Issuer der Umgebung liegt auf einer benutzerdefinierten Domäne; die Änderung muss als Issuer-Migration geplant werden.
412 precondition_failed If-Match stimmt nicht mit der aktuellen Version der Domäne überein.
503 service_unavailable Die Issuer-Informationen der Umgebung sind vorübergehend nicht verfügbar.
401 unauthenticated Die Anmeldeinformation fehlt, ist ungültig oder widerrufen.
403 insufficient_permissions Der Anmeldeinformation fehlt die erforderliche Berechtigung.
429 rate_limited Das Ratenlimit wurde überschritten; nach der Retry-After-Zeit erneut versuchen.

Beispiel

curl -X POST https://api.eu.keenauth.com/v1/custom-domains/cdom_01j9xk3m7q8r2s4t6v8w0y2z4a:make-primary \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H 'If-Match: "4"'