Domains

Register a domain

Registers a custom domain for the cluster. After registration, configure the DNS records returned in the response and call the verify endpoint to complete verification.

Required scope: domains:write

post/clusters/{cluster_id}/domains

Request

  • Base URL: http://localhost:8000
  • URL: http://localhost:8000/clusters/{cluster_id}/domains
  • Auth: API key in header API-Key

Path parameters

cluster_idstring uuid required

Headers

API-Version'2026-06-01.beta' required

Request body

domainstring required

A fully-qualified domain name.

subdomainstring

Optional subdomain prefix (e.g. auth to register auth.mycompany.com under the mycompany.com domain).

Example request

{
  "domain": "auth.mycompany.com"
}

Response

The request has succeeded and a new resource has been created as a result.

idstring uuid required
cluster_idstring uuid required
domainstring required

A fully-qualified domain name.

subdomainstring

Optional subdomain prefix.

verification_status'unverified' | 'pending' | 'verified' | 'failed' required
ssl_status'pending' | 'active' | 'failed' | 'expired' required
cname_targetstring required

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

is_activeboolean required

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

last_checked_atstring date-time

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.

last_check_errorstring

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

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "domain": "auth.mycompany.com",
  "subdomain": "auth",
  "last_check_error": "custom hostname does not CNAME to this zone."
}

Changes

No recorded changes to this operation across all 1 revision of this API.