Benutzerdefinierte Domäne hinzufügen

POST /v1/custom-domains · Berechtigung custom-domains:write

Fügt der Umgebung eine benutzerdefinierte Anmeldedomäne hinzu. Der Name wird in sein IDNA2008-A-Label umgewandelt; öffentliche Suffixe, einteilige Namen, IP-Adressen und Plattformdomänen werden abgelehnt. Ein Name ist plattformweit eindeutig: Nutzt ihn eine andere Umgebung oder wurde er vor weniger als 30 Tagen freigegeben (Quarantäne), schlägt die Anfrage mit 409 custom_domain_taken fehl. Die Domäne beginnt in pending_dns; veröffentlichen Sie die zurückgegebenen dns_records (einen dauerhaften TXT-Eigentumseintrag und einen CNAME auf den Edge-Host der Umgebung) bei Ihrem DNS-Anbieter und rufen Sie dann :verify auf oder warten Sie auf die automatische Prüfung.

Anfrage

JSON-Body (unbekannte Felder werden mit 400 unknown_field abgelehnt):

Feld Typ Erforderlich Beschreibung
Idempotency-Key header ja Erforderlich. 16-64 Zeichen [A-Za-z0-9_-]; derselbe Schlüssel mit demselben Namen liefert dieselbe Domäne.
hostname string ja Die hinzuzufügende Domäne (Unicode erlaubt), höchstens 253 Bytes, zum Beispiel login.example.com.

Antwort

201 Created mit der Domäne und einem ETag-Header.

{
  "id": "cdom_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "hostname": "login.example.com",
  "is_primary": false,
  "status": "pending_dns",
  "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": null,
  "last_checked_at": null,
  "next_check_at": "2026-10-05T09:36:00Z",
  "activated_at": null,
  "degraded_since": null,
  "status_changed_at": "2026-10-05T09:30:00.123456Z",
  "created_at": "2026-10-05T09:30:00.123456Z",
  "updated_at": "2026-10-05T09:30:00.123456Z"
}

Fehler

HTTP Code Wann
400 malformed_request Idempotency-Key fehlt oder ist fehlerhaft.
400 unknown_field Der Body enthält ein unbekanntes Feld.
403 quota_exceeded Das Kontingent an benutzerdefinierten Domänen der Umgebung ist ausgeschöpft, oder die Umgebung ist eine development-Umgebung.
409 custom_domain_taken Der Name wird von einer anderen Umgebung verwendet oder befindet sich in der 30-tägigen Quarantäne.
409 conflict Das Konto oder die Umgebung ist nicht aktiv.
415 unsupported_media_type Der Content-Type ist nicht application/json.
422 validation_failed hostname ist kein gültiger Domänenname für eine benutzerdefinierte Domäne.
422 idempotency_key_reuse Der Idempotency-Key wurde bereits mit einem anderen Body verwendet.
429 rate_limited Zu viele Versuche, heute benutzerdefinierte Domänen für das Konto hinzuzufügen; nach der Retry-After-Zeit erneut versuchen.
503 service_unavailable Das Domänenregister der Plattform oder die Kontoinformationen 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.

Beispiel

curl -X POST https://api.eu.keenauth.com/v1/custom-domains \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"hostname":"login.example.com"}'