Custom Domains

Run your links and pages on your own domain instead of the default {handle}.{PUBLIC_DOMAIN}.

Tip

Supports both apex domains (example: example.com) and subdomains (example: go.example.com).

Warning

Custom-domain mapping does not extend MCP onto your domain. MCP stays on the platform environment hostname: production uses https://{handle}.mcp.10x.in/mcp; staging/test validation uses the staging platform hostname.

What you provide vs what 10x returns

Step	You provide	10x returns
Create domain	`domain`, `defaultHandle` (optional `pathRules`)	`verification.txtName`, `verification.txtValue`
First reconcile	Domain already created	`hostedZoneId`, `nameservers[]`
Status checks	Nothing extra	`status`, `statusReason`, `ownership.nsDelegated`, `ownership.txtVerified`

Warning

verification.txtValue is returned at creation time and should be saved immediately.

How it works

Create domain mapping
Register your domain in 10x with a default handle.
Save verification values
Capture verification.txtName and verification.txtValue from the create response.
Run initial reconcile
Trigger reconcile so 10x provisions hosted-zone metadata and nameservers.
Update DNS at registrar and delegated zone
Delegate nameservers at your registrar, then add verification/traffic records in DNS.
Reconcile again
Trigger reconcile after propagation.
Go live
Domain becomes ACTIVE; public routing and redirects start resolving on your domain.

What custom domains do not cover

Custom domains currently support:

public site traffic
redirect/link traffic
domain lookup and route activation

Custom domains do not currently support:

MCP endpoints on *.mcp.<your-domain>
OAuth protected-resource metadata on your domain for MCP
per-handle MCP subdomain routing under your registrar-managed domain

Why MCP is excluded from custom domains

MCP transport depends on platform-managed wildcard DNS, certificates, OAuth discovery metadata, and handle-routing rules on the environment domain. Supporting https://{handle}.mcp.<your-domain> would require extra wildcard delegation, certificate issuance, and environment-specific OAuth metadata hosting for every customer domain. That is not part of the supported custom-domain flow today.

Domain Commerce UI screens

Use these screens in order inside Domain Management:

Screen 1: Create domain result

Immediately save:

verification.txtName
verification.txtValue (one-time)

Screen 2: Registrar records panel

Add exactly these records:

Record type	Host/Name	Value source
`NS`	apex domain (`example.com`)	`domain.nameservers[]` from `GET /v2/account/domains/{domain}` after first reconcile
`TXT`	`verification.txtName`	`verification.txtValue` from create response
`A` alias (apex)	apex domain (`example.com`)	platform edge target shown in Domain Management (copy exact target)

For subdomain-only setups, you can use CNAME to domains.{PUBLIC_DOMAIN} instead of apex alias.

Screen 3: Status timeline

Expected transition order: PENDING_DELEGATION -> (PENDING_CERT or PENDING_EDGE_DEPLOY) -> ACTIVE

If a status stalls, use statusReason as the fix instruction.

DNS values you must configure

1) Registrar nameserver delegation

Use the nameservers[] values returned by GET /v2/account/domains/{domain} after reconcile.

Record type	Host	Value
NS	apex domain (example `example.com`)	all nameservers from `nameservers[]`

2) Verification TXT record

Use the values returned in the create response:

Record type	Name	Value
TXT	`verification.txtName`	`verification.txtValue`

3) Traffic record in delegated DNS zone

Add a traffic record in the delegated zone so requests route to 10x edge.

Domain type	Record type	Name	Target
Apex domain	`A` alias	apex (example `example.com`)	platform edge target shown in Domain Management
Subdomain	`CNAME` or `A` alias (provider-dependent)	subdomain (example `go.example.com`)	platform edge target shown in Domain Management

Note

Copy DNS targets exactly as shown in the domain setup screen or API response fields for your environment.

Warning

Legacy CNAME-only setup (for example hardcoded domains.10x.in) is not sufficient for this flow.

Set up a custom domain

Open Domain Management
Go to https://app.{PUBLIC_DOMAIN} and open the domain management app.
Create domain
Click Add Domain, enter your domain, select a default handle, and submit.
Copy verification values
Save the displayed TXT name and TXT value immediately.
Run reconcile
Trigger reconcile and wait until nameservers are displayed.
Update registrar DNS
At your registrar, replace nameservers with the returned nameservers[].
Update delegated zone DNS
Add the TXT verification record and traffic record in the delegated zone.
Reconcile again and verify active
Trigger reconcile once more and wait for ACTIVE.

1) Create domain

Request

    curl -sS -X POST "https://api.10x.in/v2/account/domains" \
      -H "Authorization: Bearer <owner-jwt>" \
      -H "Content-Type: application/json" \
      -d '{
        "domain": "example.com",
        "sourceType": "BYOD_HOSTNAME",
        "defaultHandle": "acme"
      }'

Response (trimmed)

    {
      "domain": {
        "domain": "example.com",
        "status": "PENDING_DELEGATION",
        "statusReason": "awaiting_nameserver_delegation"
      },
      "verification": {
        "txtName": "_ls-verify.example.com",
        "txtValue": "lsv1...."
      }
    }

Save verification.txtName and verification.txtValue.

2) Run first reconcile

    curl -sS -X POST "https://api.10x.in/v2/account/domains/example.com/reconcile" \
      -H "Authorization: Bearer <owner-jwt>" \
      -H "Content-Type: application/json" \
      -d '{}'

3) Poll until nameservers are available

    curl -sS "https://api.10x.in/v2/account/domains/example.com" \
      -H "Authorization: Bearer <owner-jwt>"

Wait until:

domain.hostedZoneId is non-null
domain.nameservers is non-empty

4) Update registrar + DNS records

Use:

domain.nameservers[] at registrar (NS delegation)
saved verification.txtName + verification.txtValue as TXT
traffic record target from domain setup details

5) Reconcile again and wait for ACTIVE

    curl -sS -X POST "https://api.10x.in/v2/account/domains/example.com/reconcile" \
      -H "Authorization: Bearer <owner-jwt>" \
      -H "Content-Type: application/json" \
      -d '{}'

Poll status:

domain.status == "ACTIVE"
domain.ownership.nsDelegated == true
domain.ownership.txtVerified == true

Verify routing

Domain lookup contract

curl -sS "https://api.10x.in/v2/public/domain-lookup?domain=example.com"

Expected:

200
status: "ACTIVE"
handle matches your defaultHandle

Redirect behavior check

Create a known slug on the mapped handle, then request:

https://example.com/<slug>

Expect redirect response (302 or 307) to the configured destination URL.

Required auth and access

OWNER-level JWT for domain create/reconcile/routes.
Registrar access to update nameservers for your domain.
DNS access to add TXT and traffic records in the delegated zone.

Status and statusReason guide

Status	statusReason	Meaning	What to do
`PENDING_DELEGATION`	`awaiting_nameserver_delegation`	Registrar NS not delegated yet	Update registrar nameservers
`PENDING_DELEGATION`	`awaiting_txt_ownership_verification`	TXT challenge missing or wrong	Fix TXT name/value
`PENDING_EDGE_DEPLOY`	`edge_record_not_ready`	Traffic record missing or mismatched	Fix A/alias or CNAME traffic record
`PENDING_CERT`	`certificate_not_ready_for_domain`	Certificate not ready for this domain	Wait or contact support
`PENDING_CAPACITY`	`no_active_shard_capacity`	No active shard capacity	Contact support/platform admin
`ACTIVE`	`host_route_active`	Domain is live	No action needed
`FAILED`	`custom_domain_reconcile_error`	Reconcile failed unexpectedly	Retry and escalate with request IDs/logs

Troubleshooting DNS issues

Reconcile still awaiting_nameserver_delegation: check authoritative NS with dig +short NS <domain>.
Reconcile still awaiting_txt_ownership_verification: check TXT with dig +short TXT <txtName>.
edge_record_not_ready: verify only one canonical traffic record exists for host and points to platform target.
FAILED/custom_domain_reconcile_error: re-run reconcile, then escalate with response payload and timestamp.

Custom Domains

Tip

Warning

What you provide vs what 10x returns

Warning

How it works

Create domain mapping

Save verification values

Run initial reconcile

Update DNS at registrar and delegated zone

Reconcile again

Go live

What custom domains do not cover

Why MCP is excluded from custom domains

Domain Commerce UI screens

Screen 1: Create domain result

Screen 2: Registrar records panel

Screen 3: Status timeline

DNS values you must configure

1) Registrar nameserver delegation

2) Verification TXT record

3) Traffic record in delegated DNS zone

Note

Warning

Set up a custom domain

Open Domain Management

Create domain

Copy verification values

Run reconcile

Update registrar DNS

Update delegated zone DNS

Reconcile again and verify active

1) Create domain

Request

Response (trimmed)

2) Run first reconcile

3) Poll until nameservers are available

4) Update registrar + DNS records

5) Reconcile again and wait for ACTIVE

Verify routing

Domain lookup contract

Redirect behavior check

Required auth and access

Status and statusReason guide

Troubleshooting DNS issues

Related

Getting Started

Short Links

Advanced Link Controls

Troubleshooting

Unlock the rest of this page