Skip to main content
You need a root key with the permissions listed on this page. Create one in the dashboard under Settings > Root Keys. See Permission reference for every permission.
Attach a custom domain to an and start it. The domain starts as pending and serves no traffic until verification succeeds. We check DNS about once a minute, so expect a short delay after you add your records. The response’s dnsRecords lists every record you need. Create each one exactly as given: one routes traffic and one proves you own the domain, and you need both. If your DNS provider supports Domain Connect, the response also has a domainConnect.url that adds the records for you in one step.
  • A name that already exists in your workspace returns a 409.
  • Going over your plan’s domain limit returns a 403. See Limits.
  • If the records aren’t found within 24 hours, the domain moves to failed. Use verify-domain to try again.

​
Usage

​
Flags

​
string
required
App ID or slug.
​
string
required
Fully qualified domain name, for example api.acme.com. Wildcards (*.acme.com), public suffixes (co.uk, github.io), IP addresses, and anything with a scheme, port, or path return a 400. Names are stored lowercase, with Unicode converted to Punycode, so MÜNCHEN.DE and xn--mnchen-3ya.de are the same domain.
​
string
required
Environment ID or slug the domain routes to.
​
string
required
Project ID or slug. Both forms resolve to the same project.

​
Shared flags

Every unkey api command accepts these; CLI output and shared flags describes them in full.
​
string
A JSON document sent as the request body instead of building it from the flags above. It is mutually exclusive with the request-building flags, and unknown fields are rejected locally. See Send a raw body.
​
string
Root key for the request. Falls back to UNKEY_ROOT_KEY, then to the config file written by unkey auth login. See CLI authentication.
​
string
default:"https://api.unkey.com"
Base URL of the API. Falls back to UNKEY_API_BASE_URL. You don’t normally need to set it.
​
string
default:"~/.unkey/config.toml"
Path of the TOML file that unkey auth login writes. Falls back to UNKEY_CONFIG.
​
string
Output format. Falls back to UNKEY_OUTPUT. Set json to print the full response envelope (meta and data) for piping; any other value prints the request ID followed by data.

​
Required permissions

Your root key needs one of:
  • environment.*.create_domain (any environment)
  • environment.<environment_id>.create_domain (a specific environment)
If the environment doesn’t exist or your key doesn’t have the permission, you get the same 404: The requested environment does not exist. See Root key permissions for the full catalog.

​
Examples

Attach a domain and print the DNS records:
Send the request body as JSON:

​
API endpoint

The command calls POST /v2/domains.createDomain and prints its response. The request fields carry the same names as the flags in camelCase, which is the shape --body expects.

Custom domains

DNS records, verification, and certificates for your own hostnames.
Last modified on September 29, 2026