Custom domains

Three requests put a service on your own domain. Attach the domain, create the DNS records the response gives you, then ask for a verify. HTTPS follows on its own.

4 min read

These routes need PLATFORM_API, with WRITE for anything but reading. They work on web services and static sites. For what happens behind each step, see Custom domains.

1. Attach the domain

bash

curl -X POST "https://api.naijacloud.com/v1/services/$SERVICE_ID/custom-domains" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"www.acme.ng"}'

The response is the domain, still PENDING, with the records it needs. The first is the ownership proof: nothing routes until it is published.

Response

json

{
  "id": "7d0e…",
  "serviceId": "c1a9…",
  "domain": "www.acme.ng",
  "status": "PENDING",
  "lastCheck": "Add the TXT record _naijacloud-verify.www.acme.ng shown below to prove you own this domain, then Verify.",
  "dnsTarget": {
    "cname": "storefront-api.naijacloud.app",
    "aRecord": null,
    "isApex": false,
    "records": [
      { "type": "TXT", "name": "_naijacloud-verify.www.acme.ng", "value": "naijacloud-verify=3f9c…", "purpose": "ownership" },
      { "type": "CNAME", "name": "www.acme.ng", "value": "storefront-api.naijacloud.app", "purpose": "routing" }
    ],
    "conflicts": []
  },
  "verifiedAt": null,
  "ownershipVerifiedAt": null,
  "createdAt": "2026-10-19T09:12:00.000Z"
}

2. Publish the records

Create every record in dnsTarget.records wherever the domain's DNS lives. Remove anything listed in dnsTarget.conflicts: an old record at the same name blocks verification.

The ownership TXT record proves your workspace owns the domain. One on the root domain covers its subdomains. It is not needed when the domain sits in a DNS zone your workspace holds on Naijacloud.
A 409 on attach means another workspace has the domain. Its message gives your TXT record; publish it and attach again to move the domain to you.
A subdomain such as www gets a CNAME.
An apex domain such as acme.ng cannot hold a CNAME, so isApex is true and the records say what to create instead.

If the domain's DNS is on Naijacloud, add the records under Domains in the dashboard. See DNS records.

3. Verify

DNS takes its own time. Ask for a check once the records are in place:

Verify

bash

curl -X POST "https://api.naijacloud.com/v1/custom-domains/$DOMAIN_ID/verify" \
  -H "Authorization: Bearer $NC_API_KEY"

status becomes ACTIVE when the records resolve: ownershipVerifiedAt is set once the TXT record is found, and the routing record follows. Until then lastCheck says what the check found. Attaching the domain started a redeploy that adds the route and the certificate, so allow a minute or two before the first HTTPS request.

List and remove

A service's domains

bash

curl "https://api.naijacloud.com/v1/services/$SERVICE_ID/custom-domains" \
  -H "Authorization: Bearer $NC_API_KEY"

Detach a domain

bash

curl -X DELETE "https://api.naijacloud.com/v1/custom-domains/$DOMAIN_ID" \
  -H "Authorization: Bearer $NC_API_KEY"

Detaching returns 204. The domain stops serving after the redeploy that follows. Remove the DNS records too, so nobody else can claim a name that still points at us.

To buy a new domain over the API, search, check and order it under /v1/registered-domains; an order returns a checkout link to pay. See the Domains and DNS reference and Registering a domain.

Related: Custom domains reference.