# 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.

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

```bash
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"}'
```