---
title: "Register a domain"
method: POST
path: "/clusters/{cluster_id}/domains"
tags: ["Domains"]
---

# Register a domain

`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`

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`

## Path parameters

- `cluster_id` string, uuid, required

## Headers

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

## Request body

- CreateDomainRequest
  - `domain` string, required: A fully-qualified domain name.
  - `subdomain` string: Optional subdomain prefix (e.g. `auth` to register `auth.mycompany.com` under the `mycompany.com` domain).

## Response `201`

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

- Domain: A custom domain registered to a cluster.
  - `id` string, uuid, required
  - `cluster_id` string, uuid, required
  - `domain` string, required: A fully-qualified domain name.
  - `subdomain` string: Optional subdomain prefix.
  - `verification_status` 'unverified' | 'pending' | 'verified' | 'failed', required
  - `ssl_status` 'pending' | 'active' | 'failed' | 'expired', required
  - `cname_target` string, required: CNAME target. Point your domain's DNS CNAME record to this value to route traffic to the cluster.
  - `dns_records` DnsRecord[], required: DNS records to configure for domain verification and routing.
    - `type` 'CNAME' | 'TXT', required
    - `name` string, required: The DNS record name (host).
    - `value` string, required: The DNS record value (target).
  - `is_active` boolean, required: `true` when the domain is verified and its SSL certificate is active.
  - `last_checked_at` string, 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_error` string: Cloudflare's reason the domain is not active yet, from the last check. Absent when there is none.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: The server could not understand the request due to invalid syntax.
- `401`: Access is unauthorized.
- `402`: Client error
- `403`: Access is forbidden.
- `404`: The server cannot find the requested resource.
- `409`: The request conflicts with the current state of the server.
- `422`: Client error
- `429`: Client error
- `500`: Server error
- `501`: Server error

---

[API](https://skmtc.dev/skycloak/apis/skycloak-public-api.md) · [All operations](https://skmtc.dev/skycloak/apis/skycloak-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skycloak/apis/skycloak-public-api/revisions/33a69e2ce35f?raw)