Check a custom domain's DNS now

POST /v1/custom-domains/{custom_domain_id}:verify · permission custom-domains:write

Runs the DNS check (TXT ownership record, CNAME and CAA, through a DNSSEC-validating resolver) immediately, applies the result to the domain's status and returns the updated domain. A disabled domain, or a pending_dns domain whose retry window has ended, is restarted first. If the cell's DNS resolver is not configured in this deployment the check is refused with 503 so that an inconclusive check never looks like success.

Request

Field	Type	Required	Description
`custom_domain_id`	string	yes	Custom domain ID (`cdom_…`).
`Idempotency-Key`	header	no	Optional key (16-64 characters) that makes a retried request safe.

No request body.

Response

200 OK with the updated domain and an ETag header.

{
  "id": "cdom_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "hostname": "login.example.com",
  "is_primary": false,
  "status": "issuing",
  "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": "2026-10-05T09:31:00Z",
  "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"
}

Errors

HTTP	code	When
404	`not_found`	The custom domain does not exist or belongs to another environment.
409	`custom_domain_state_conflict`	The domain is `released`.
409	`conflict`	A concurrent check changed the domain; retry.
503	`service_unavailable`	The DNS resolver is not configured in this deployment, or a dependency is temporarily unavailable.
401	`unauthenticated`	The credential is missing, invalid or revoked.
403	`insufficient_permissions`	The credential lacks the required permission.
429	`rate_limited`	The rate limit was exceeded; retry after the `Retry-After` period.

Example

curl -X POST https://api.eu.keenauth.com/v1/custom-domains/cdom_01j9xk3m7q8r2s4t6v8w0y2z4a:verify \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"