Aggiungere un dominio personalizzato

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

Aggiunge un dominio di accesso personalizzato all'ambiente. Il nome è convertito nella sua A-label IDNA2008; suffissi pubblici, nomi a un'etichetta, indirizzi IP e domini della piattaforma sono rifiutati. Un nome è unico sull'intera piattaforma: se un altro ambiente lo usa, o è stato rilasciato meno di 30 giorni fa (quarantena), la richiesta fallisce con 409 custom_domain_taken. Il dominio parte in pending_dns; pubblica i dns_records restituiti (un record TXT di proprietà permanente e un CNAME verso l'host edge dell'ambiente) presso il tuo provider DNS, poi chiama :verify o attendi il controllo automatico.

Richiesta

Corpo JSON (i campi sconosciuti sono rifiutati con 400 unknown_field):

Campo Tipo Obbligatorio Descrizione
Idempotency-Key header sì Obbligatorio. 16-64 caratteri [A-Za-z0-9_-]; ripetere la stessa chiave con lo stesso nome restituisce lo stesso dominio.
hostname string sì Il dominio da aggiungere (Unicode ammesso), al massimo 253 byte, per esempio login.example.com.

Risposta

201 Created con il dominio e un'intestazione 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"
}

Errori

HTTP code Quando
400 malformed_request Idempotency-Key manca o non è valida.
400 unknown_field Il corpo contiene un campo sconosciuto.
403 quota_exceeded La quota di domini personalizzati dell'ambiente è esaurita, oppure l'ambiente è di tipo development.
409 custom_domain_taken Il nome è usato da un altro ambiente o è nella quarantena di 30 giorni.
409 conflict L'account o l'ambiente non è attivo.
415 unsupported_media_type Il tipo di contenuto non è application/json.
422 validation_failed hostname non è un nome di dominio valido per un dominio personalizzato.
422 idempotency_key_reuse L'Idempotency-Key è già stata usata con un corpo diverso.
429 rate_limited Troppi tentativi di aggiunta di domini personalizzati per l'account oggi; riprova dopo il periodo Retry-After.
503 service_unavailable Il registro dei domini della piattaforma o le informazioni sull'account dell'ambiente sono temporaneamente non disponibili.
401 unauthenticated La credenziale manca, non è valida o è stata revocata.
403 insufficient_permissions La credenziale non ha il permesso richiesto.

Esempio

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