Create domain

Attach a custom domain to an environment and start verifying it.

The domain is created in the pending state and does not serve traffic until verification succeeds. Verification runs in the background and polls DNS, so it is eventually consistent.

The response returns dnsRecords: every record needed to finish setup, already resolved for whether this domain is an apex or a subdomain. Create every entry exactly as given. One record establishes routing and one proves ownership, and both are needed: whether ownership can be inferred from the routing record depends on how your provider publishes it, and a name another workspace has already verified can only be claimed through the ownership record. Neither is knowable before the records exist.

When your DNS provider supports Domain Connect, the response also carries a domainConnect object; opening its url applies the same records at the provider in one step. The object is absent when the shortcut is unavailable.

Domains are unique per workspace, so the same name cannot be attached to two environments. Attaching a domain that already exists in your workspace returns a 409 conflict.

How many domains you may attach is set by your plan. Attaching one beyond that allowance returns a 403; upgrade the plan or remove a domain you no longer need.

Important: verification stops after 24 hours without the required DNS records, and the domain moves to failed.

Required Permissions

Your root key must have one of the following permissions:

environment.*.create_domain (to attach domains to any environment)
environment.<environment_id>.create_domain (to attach domains to a specific environment)

POST

domains.createDomain

Typescript (SDK)

import { Unkey } from "@unkey/api";

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
});

async function run() {
  const result = await unkey.domains.createDomain({
    project: "payments",
    app: "payments-api",
    environment: "production",
    domain: "acme.com",
  });

  console.log(result);
}

run();

curl --request POST \
  --url https://api.unkey.com/v2/domains.createDomain \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "app": "payments-api",
  "domain": "acme.com",
  "environment": "production",
  "project": "payments"
}
'

import requests

url = "https://api.unkey.com/v2/domains.createDomain"

payload = {
    "app": "payments-api",
    "domain": "acme.com",
    "environment": "production",
    "project": "payments"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    app: 'payments-api',
    domain: 'acme.com',
    environment: 'production',
    project: 'payments'
  })
};

fetch('https://api.unkey.com/v2/domains.createDomain', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unkey.com/v2/domains.createDomain",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'app' => 'payments-api',
    'domain' => 'acme.com',
    'environment' => 'production',
    'project' => 'payments'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unkey.com/v2/domains.createDomain"

	payload := strings.NewReader("{\n  \"app\": \"payments-api\",\n  \"domain\": \"acme.com\",\n  \"environment\": \"production\",\n  \"project\": \"payments\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.unkey.com/v2/domains.createDomain")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"app\": \"payments-api\",\n  \"domain\": \"acme.com\",\n  \"environment\": \"production\",\n  \"project\": \"payments\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unkey.com/v2/domains.createDomain")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"app\": \"payments-api\",\n  \"domain\": \"acme.com\",\n  \"environment\": \"production\",\n  \"project\": \"payments\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "dnsRecords": [
      {
        "name": "acme.com",
        "note": "Apex domains cannot hold a CNAME. Use ALIAS, ANAME, or a flattened CNAME depending on your provider.",
        "type": "ALIAS",
        "value": "a1b2c3d4e5f6g7h8.cname.unkey.com",
        "verified": false
      },
      {
        "name": "_unkey.acme.com",
        "note": "Proves ownership. An apex domain cannot be verified through its routing record, so this is the only proof available.",
        "type": "TXT",
        "value": "unkey-domain-verify=3ZQ8xK1mP7vT5nR2wY6bJ4hL",
        "verified": false
      }
    ],
    "domainId": "dom_1234abcd"
  },
  "meta": {
    "requestId": "req_1234abcd"
  }
}

Authorizations

Authorization

string

header

required

Unkey uses bearer tokens for authentication. Public integrations use root keys, while the dashboard proxy uses short-lived JWTs. To authenticate, include the token in the Authorization header of each request:

Authorization: Bearer unkey_123

Root keys have specific permissions attached to them, controlling what operations they can perform. Legacy permissions use tuple strings like api.*.create_key; resource permissions use Unkey Resource Names plus actions, like unkey:v1:ws_123:keyspaces/*#create_key. Security best practices:

Keep root keys secure and never expose them in client-side code
Use different root keys for different environments
Rotate keys periodically, especially after team member departures
Create keys with minimal necessary permissions following least privilege principle
Monitor key usage with audit logs.

Body

application/json

project

string

required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

Required string length: 3 - 255

Pattern: ^[a-zA-Z0-9_-]+$

Example:

"proj_1234abcd"

app

string

required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

Required string length: 3 - 255

Pattern: ^[a-zA-Z0-9_-]+$

Example:

"proj_1234abcd"

environment

string

required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

Required string length: 3 - 255

Pattern: ^[a-zA-Z0-9_-]+$

Example:

"proj_1234abcd"

domain

string

required

Fully qualified domain name to attach to the environment, without a scheme, port, or path. Must be unique across your entire workspace: the same name cannot be attached to two environments.

The name must sit under a registrable domain: 'api.acme.co.uk' is accepted, the public suffix 'co.uk' itself is not. Internationalized names may be sent in Unicode or Punycode form; either way the domain is stored and returned in its canonical form, lowercase ASCII with Unicode labels Punycode encoded, and the DNS records in the response use that form.

Required string length: 4 - 253

Example:

"api.acme.com"

Response

Domain created and verification started. The domain is pending until the DNS records resolve.

meta

object

required

Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The requestId is particularly important when troubleshooting issues with the Unkey support team.

Show child attributes

data

object

required

Show child attributes

Last modified on August 25, 2026

⌘I

Typescript (SDK)

import { Unkey } from "@unkey/api";

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
});

async function run() {
  const result = await unkey.domains.createDomain({
    project: "payments",
    app: "payments-api",
    environment: "production",
    domain: "acme.com",
  });

  console.log(result);
}

run();

curl --request POST \
  --url https://api.unkey.com/v2/domains.createDomain \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "app": "payments-api",
  "domain": "acme.com",
  "environment": "production",
  "project": "payments"
}
'

import requests

url = "https://api.unkey.com/v2/domains.createDomain"

payload = {
    "app": "payments-api",
    "domain": "acme.com",
    "environment": "production",
    "project": "payments"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    app: 'payments-api',
    domain: 'acme.com',
    environment: 'production',
    project: 'payments'
  })
};

fetch('https://api.unkey.com/v2/domains.createDomain', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unkey.com/v2/domains.createDomain",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'app' => 'payments-api',
    'domain' => 'acme.com',
    'environment' => 'production',
    'project' => 'payments'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unkey.com/v2/domains.createDomain"

	payload := strings.NewReader("{\n  \"app\": \"payments-api\",\n  \"domain\": \"acme.com\",\n  \"environment\": \"production\",\n  \"project\": \"payments\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.unkey.com/v2/domains.createDomain")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"app\": \"payments-api\",\n  \"domain\": \"acme.com\",\n  \"environment\": \"production\",\n  \"project\": \"payments\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unkey.com/v2/domains.createDomain")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"app\": \"payments-api\",\n  \"domain\": \"acme.com\",\n  \"environment\": \"production\",\n  \"project\": \"payments\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "dnsRecords": [
      {
        "name": "acme.com",
        "note": "Apex domains cannot hold a CNAME. Use ALIAS, ANAME, or a flattened CNAME depending on your provider.",
        "type": "ALIAS",
        "value": "a1b2c3d4e5f6g7h8.cname.unkey.com",
        "verified": false
      },
      {
        "name": "_unkey.acme.com",
        "note": "Proves ownership. An apex domain cannot be verified through its routing record, so this is the only proof available.",
        "type": "TXT",
        "value": "unkey-domain-verify=3ZQ8xK1mP7vT5nR2wY6bJ4hL",
        "verified": false
      }
    ],
    "domainId": "dom_1234abcd"
  },
  "meta": {
    "requestId": "req_1234abcd"
  }
}