Añadir un dominio personalizado

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

Añade un dominio de inicio de sesión personalizado al entorno. El nombre se convierte a su A-label IDNA2008; se rechazan sufijos públicos, nombres de una sola etiqueta, direcciones IP y dominios de la plataforma. Un nombre es único en toda la plataforma: si otro entorno lo usa, o se liberó hace menos de 30 días (cuarentena), la solicitud falla con 409 custom_domain_taken. El dominio empieza en pending_dns; publique los dns_records devueltos (un registro TXT de propiedad permanente y un CNAME al host edge del entorno) en su proveedor DNS y luego llame a :verify o espere a la comprobación automática.

Solicitud

Cuerpo JSON (los campos desconocidos se rechazan con 400 unknown_field):

Campo Tipo Requerido Descripción
Idempotency-Key header sí Obligatorio. 16-64 caracteres [A-Za-z0-9_-]; repetir la misma clave con el mismo nombre devuelve el mismo dominio.
hostname string sí El dominio que se añade (se admite Unicode), como máximo 253 bytes, por ejemplo login.example.com.

Respuesta

201 Created con el dominio y un encabezado 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"
}

Errores

HTTP código Cuándo
400 malformed_request Idempotency-Key falta o no es válida.
400 unknown_field El cuerpo contiene un campo desconocido.
403 quota_exceeded La cuota de dominios personalizados del entorno está completa, o el entorno es de tipo development.
409 custom_domain_taken El nombre lo usa otro entorno o está en su cuarentena de 30 días.
409 conflict La cuenta o el entorno no está activo.
415 unsupported_media_type El tipo de contenido no es application/json.
422 validation_failed hostname no es un nombre de dominio válido para un dominio personalizado.
422 idempotency_key_reuse La Idempotency-Key ya se usó con un cuerpo distinto.
429 rate_limited Demasiados intentos de añadir dominios personalizados para la cuenta hoy; reintente después del periodo Retry-After.
503 service_unavailable El registro de dominios de la plataforma o la información de la cuenta del entorno no está disponible temporalmente.
401 unauthenticated La credencial falta, no es válida o fue revocada.
403 insufficient_permissions La credencial no tiene el permiso requerido.

Ejemplo

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