# Özel alan ekle

`POST /v1/custom-domains` · izin `custom-domains:write`

Ortama bir özel giriş alan adı ekler. Ad IDNA2008 A-etiketine çevrilir; genel sonekler, tek etiketli adlar, IP adresleri ve platform alanları reddedilir. Ad platform genelinde tekildir: başka bir ortam kullanıyorsa ya da 30 günden kısa süre önce bırakıldıysa (karantina) istek `409 custom_domain_taken` ile reddedilir. Alan `pending_dns` durumunda başlar; dönen `dns_records` kayıtlarını (kalıcı TXT sahiplik kaydı ve ortamın kenar host'una CNAME) DNS sağlayıcınızda yayımlayın, sonra `:verify` çağırın ya da otomatik denetimi bekleyin.

## İstek

JSON gövdesi (bilinmeyen alanlar `400 unknown_field` ile reddedilir):

| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| `Idempotency-Key` | başlık | evet | Zorunlu. 16-64 karakter `[A-Za-z0-9_-]`; aynı anahtar aynı adla yinelenirse aynı alan döner. |
| `hostname` | string | evet | Eklenecek ad (Unicode olabilir), en çok 253 bayt; örneğin `login.example.com`. |

## Yanıt

`201 Created`; alan ve `ETag` başlığı.

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

## Hatalar

| HTTP | code | Ne zaman |
|---|---|---|
| 400 | `malformed_request` | `Idempotency-Key` yok ya da biçimsiz. |
| 400 | `unknown_field` | Gövdede bilinmeyen bir alan var. |
| 403 | `quota_exceeded` | Ortamın özel alan kotası dolu ya da ortam bir `development` ortamı. |
| 409 | `custom_domain_taken` | Ad başka bir ortamda kullanılıyor ya da 30 günlük karantinada. |
| 409 | `conflict` | Hesap ya da ortam etkin değil. |
| 415 | `unsupported_media_type` | İçerik türü `application/json` değil. |
| 422 | `validation_failed` | `hostname` özel alan için geçerli bir alan adı değil. |
| 422 | `idempotency_key_reuse` | `Idempotency-Key` başka bir gövdeyle zaten kullanıldı. |
| 429 | `rate_limited` | Hesap bugün çok fazla özel alan ekleme denemesi yaptı; `Retry-After` süresinden sonra yeniden deneyin. |
| 503 | `service_unavailable` | Platform alan kayıt defteri ya da ortamın hesap bilgisi geçici olarak kullanılamıyor. |
| 401 | `unauthenticated` | Kimlik bilgisi yok, geçersiz ya da iptal edilmiş. |
| 403 | `insufficient_permissions` | Kimlik bilgisinde gerekli izin yok. |

## Örnek

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