Ajouter un domaine personnalisé

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

Ajoute un domaine de connexion personnalisé à l'environnement. Le nom est converti en A-label IDNA2008 ; les suffixes publics, les noms à une seule étiquette, les adresses IP et les domaines de la plateforme sont refusés. Un nom est unique sur toute la plateforme : s'il est utilisé par un autre environnement ou a été libéré il y a moins de 30 jours (quarantaine), la requête échoue avec 409 custom_domain_taken. Le domaine démarre en pending_dns ; publiez les dns_records renvoyés (un enregistrement TXT de propriété permanent et un CNAME vers l'hôte edge de l'environnement) chez votre fournisseur DNS, puis appelez :verify ou attendez la vérification automatique.

Requête

Corps JSON (les champs inconnus sont rejetés avec 400 unknown_field) :

Champ Type Obligatoire Description
Idempotency-Key header oui Obligatoire. 16-64 caractères [A-Za-z0-9_-] ; répéter la même clé avec le même nom renvoie le même domaine.
hostname string oui Le domaine à ajouter (Unicode autorisé), 253 octets au plus, par exemple login.example.com.

Réponse

201 Created avec le domaine et un en-tête 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"
}

Erreurs

HTTP code Quand
400 malformed_request Idempotency-Key est absent ou mal formé.
400 unknown_field Le corps contient un champ inconnu.
403 quota_exceeded Le quota de domaines personnalisés de l'environnement est atteint, ou l'environnement est de type development.
409 custom_domain_taken Le nom est utilisé par un autre environnement ou est dans sa quarantaine de 30 jours.
409 conflict Le compte ou l'environnement n'est pas actif.
415 unsupported_media_type Le type de contenu n'est pas application/json.
422 validation_failed hostname n'est pas un nom de domaine valide pour un domaine personnalisé.
422 idempotency_key_reuse L'Idempotency-Key a déjà été utilisée avec un autre corps.
429 rate_limited Trop de tentatives d'ajout de domaine personnalisé pour le compte aujourd'hui ; réessayez après le délai Retry-After.
503 service_unavailable Le registre de domaines de la plateforme ou les informations de compte de l'environnement sont temporairement indisponibles.
401 unauthenticated L'identifiant est absent, invalide ou révoqué.
403 insufficient_permissions L'identifiant n'a pas la permission requise.

Exemple

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