Verify a domain

POST

/clusters/{cluster_id}/domains/{domain_id}/verify

curl --request POST \
  --url http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/domains/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/verify \
  --header 'API-Key: <API-Key>' \
  --header 'API-Version: 2026-06-01.beta'

• Local development

Checks the current DNS configuration and refreshes the domain’s verification status. Call this after configuring the required DNS records.

Required scope: domains:read

Authorizations

• ApiKeyAuth

Parameters

Path Parameters

cluster_id

required

string format: uuid

domain_id

required

string format: uuid

Header Parameters

API-Version

required

string

Allowed values: 2026-06-01.beta

Responses

200

The request has succeeded.

Media typeapplication/json

A custom domain registered to a cluster.

object

id

required

string format: uuid

cluster_id

required

string format: uuid

domain

required

The registered custom domain.

string

>= 3 characters <= 253 characters /^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$/

subdomain

Optional subdomain prefix.

string

verification_status

required

string

Allowed values: unverified pending verified failed

ssl_status

required

string

Allowed values: pending active failed expired

cname_target

required

CNAME target. Point your domain’s DNS CNAME record to this value to route traffic to the cluster.

string

dns_records

required

DNS records to configure for domain verification and routing.

Array<object>

A DNS record to configure in your domain’s DNS settings.

object

type

required

string

Allowed values: CNAME TXT

name

required

The DNS record name (host).

string

value

required

The DNS record value (target).

string

is_active

required

true when the domain is verified and its SSL certificate is active.

boolean

last_checked_at

When Skycloak last checked this domain’s status with Cloudflare. Pending domains are checked every few minutes for 48 hours, then hourly, then daily after 30 days. Absent until the first check.

string format: date-time

last_check_error

Cloudflare’s reason the domain is not active yet, from the last check. Absent when there is none.

string

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "domain": "auth.mycompany.com",
  "subdomain": "auth",
  "verification_status": "unverified",
  "ssl_status": "pending",
  "dns_records": [
    {
      "type": "CNAME"
    }
  ],
  "last_check_error": "custom hostname does not CNAME to this zone."
}

401

Access is unauthorized.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

403

Access is forbidden.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

404

The server cannot find the requested resource.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

429

Client error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Headers

Retry-After

integer

RateLimit-Limit

integer

RateLimit-Remaining

integer

RateLimit-Reset

integer

X-RateLimit-Limit-Second

integer

X-RateLimit-Remaining-Second

integer

X-RateLimit-Limit-Minute

integer

X-RateLimit-Remaining-Minute

integer

X-RateLimit-Limit-Hour

integer

X-RateLimit-Remaining-Hour

integer

X-RateLimit-Limit-Day

integer

X-RateLimit-Remaining-Day

integer

500

Server error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

501

Server error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}