カスタムドメインを追加

POST /v1/custom-domains · 権限 custom-domains:write

環境にカスタムログインドメインを追加します。名前は IDNA2008 の A ラベルに変換され、パブリックサフィックス、単一ラベル名、IP アドレス、プラットフォームのドメインは拒否されます。名前はプラットフォーム全体で一意です。別の環境が使用している場合、または解放から 30 日未満 (隔離中) の場合は 409 custom_domain_taken で失敗します。ドメインは pending_dns で始まります。返された dns_records (恒久的な TXT 所有権レコードと環境のエッジホストへの CNAME) を DNS プロバイダーに公開し、:verify を呼び出すか自動チェックを待ってください。

リクエスト

JSON ボディ (未知のフィールドは 400 unknown_field で拒否されます):

フィールド タイプ 必須 説明
Idempotency-Key header はい 必須。16-64 文字の [A-Za-z0-9_-]。同じキーを同じ名前で繰り返すと同じドメインを返します。
hostname string はい 追加するドメイン (Unicode 可)、最大 253 バイト。例: login.example.com。

レスポンス

201 Created とドメイン、ETag ヘッダー。

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

エラー

HTTP コード 概要
400 malformed_request Idempotency-Key がないか、形式が不正です。
400 unknown_field ボディに未知のフィールドが含まれています。
403 quota_exceeded 環境のカスタムドメインの割り当てが上限に達しているか、環境が development 環境です。
409 custom_domain_taken 名前は別の環境で使用中か、30 日間の隔離中です。
409 conflict アカウントまたは環境が有効ではありません。
415 unsupported_media_type コンテンツタイプが application/json ではありません。
422 validation_failed hostname はカスタムドメインとして有効なドメイン名ではありません。
422 idempotency_key_reuse Idempotency-Key は別のボディですでに使用されています。
429 rate_limited 本日のアカウントのカスタムドメイン追加の試行が多すぎます。Retry-After の時間が経過してから再試行してください。
503 service_unavailable プラットフォームのドメインレジストリまたは環境のアカウント情報が一時的に利用できません。
401 unauthenticated 認証情報がない、無効、または失効しています。
403 insufficient_permissions 認証情報に必要な権限がありません。

例

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