CustomDomain Docs
ReferenceAPI referenceManaged DNS

Start managed DNS for a connection's domain

Start managed DNS for a connection's domain: CustomDomain™ API reference in the managed dns group. Covers parameters, request body, responses and error codes.

POST
/connections/{id}/managed-dns

Offers the connection's end user a one-time change instead of typing records: point the domain's nameservers at CustomDomain™, and we host the zone and write every record from then on.

The first call creates a hosted zone for the connection's REGISTRABLE domain (acme.com, also for shop.acme.com), copies the records the domain already serves at common names (apex A/AAAA/MX/TXT/CAA, www, mail hosts, DMARC, common DKIM selectors, common SRV names, and every name the connection needs) so nothing breaks at the switch, adds the records CustomDomain™ needs for the connection, looks up the registrar, and answers 201 with the zone. Later calls answer 200 with the same zone; nothing is created twice. A second connection under the same registrable domain joins the existing zone. The zone becomes active once every nameserver the registry lists for the domain is ours; the connection then verifies and goes live on its own.

Available only when managed_dns.available is true on POST /v1/domains:check (the deployment flag is on, and the domain's nameservers can be changed at a registrar). Authorized like the other connection routes: an API key within the tenant, or a widget token of the connection's own application (and domain, when the token is bound to one).

The end user's widget token (scope connect) can start it only when the application offers DNS hosting on CustomDomain™: its nameserver_migration setting has mode offer or prefer and target managed. With the setting off the call answers 403 forbidden with the details "this application does not offer nameserver migration"; with target dns_host or custom it answers 403 forbidden with "this application hosts its users' DNS elsewhere; the nameserver move is its offer". Either way no zone is created. A connection that already has a zone can still call it, to resume. API keys and app-scoped tokens are not limited by the setting, and reading or editing an existing zone's records is unchanged. managed_dns on POST /v1/domains:check stays the deployment's and the domain's verdict; it does not say whether the application offers hosting.

The end user's widget token acts only on what is its own. A connection that names an end user (end_user_ref) is the token's when that is the token's own end_user_ref (mint the token with it); a connection that names none (an API key made it) is the token's only when its domain is one the token is bound to. A token with an end_user_ref and no bound domain owns none of those, and a token with no end_user_ref and no bound domain counts only this connection's domain. The call's connection must be the token's: a connection of another end user answers 403 token_wrong_end_user before anything is created or linked (the create call refuses a token for that end user's exact name too, so it is not handed that connection's id). One zone serves the whole registrable domain, so a zone that already exists is started, joined or resumed only when every connection linked to it is the token's too. Another end user's zone, one that also holds another name's connection of the platform (made with an API key) or a connection of another application, and one nobody is linked to (the end user removed its last connection; the platform's API key starts it for the new one) answer 409 conflict, "the DNS of acme.com is already hosted by CustomDomain™ for someone else"; nothing is linked or written and the answer shows none of the zone. A zone this call creates is the caller's. Two starts at once by one end user on a new zone can answer one of them 409; the same call again succeeds. API keys and app-scoped tokens are not limited by it.

AuthorizationBearer <token>

Long-lived tenant API key, cd_live_… (production) or cd_test_… (staging, development), stored hashed. Keys created before the switch to cd_ start with sk_live_… / sk_test_… and are still accepted. Scoped to the owning application's tenant.

In: header

Path Parameters

id*string

Request Body

application/json

No parameters. Send no body, or {}.

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/connections/string/managed-dns" \  -H "Content-Type: application/json" \  -d '{}'
{  "zone": "acme.com",  "status": "awaiting_delegation",  "nameservers": [    "string"  ],  "observed_nameservers": [    "string"  ],  "registrar": {    "name": "string",    "url": "string"  },  "records": [    {      "id": "mdr_1f3a9c0b7d2e5a4c6b8d",      "type": "A",      "name": "string",      "value": "string",      "ttl": 0,      "priority": 0,      "source": "discovered"    }  ],  "warnings": [    "string"  ],  "checked_at": "2019-08-24T14:15:22Z",  "activated_at": "2019-08-24T14:15:22Z"}
{  "zone": "acme.com",  "status": "awaiting_delegation",  "nameservers": [    "string"  ],  "observed_nameservers": [    "string"  ],  "registrar": {    "name": "string",    "url": "string"  },  "records": [    {      "id": "mdr_1f3a9c0b7d2e5a4c6b8d",      "type": "A",      "name": "string",      "value": "string",      "ttl": 0,      "priority": 0,      "source": "discovered"    }  ],  "warnings": [    "string"  ],  "checked_at": "2019-08-24T14:15:22Z",  "activated_at": "2019-08-24T14:15:22Z"}
{  "code": "account_not_verifiable",  "title": "string",  "details": "string",  "challenge": {    "value": "string",    "bits": 1,    "expires_at": "2019-08-24T14:15:22Z"  }}
{  "code": "account_not_verifiable",  "title": "string",  "details": "string",  "challenge": {    "value": "string",    "bits": 1,    "expires_at": "2019-08-24T14:15:22Z"  }}
{  "code": "account_not_verifiable",  "title": "string",  "details": "string",  "challenge": {    "value": "string",    "bits": 1,    "expires_at": "2019-08-24T14:15:22Z"  }}
{  "code": "account_not_verifiable",  "title": "string",  "details": "string",  "challenge": {    "value": "string",    "bits": 1,    "expires_at": "2019-08-24T14:15:22Z"  }}
{  "code": "account_not_verifiable",  "title": "string",  "details": "string",  "challenge": {    "value": "string",    "bits": 1,    "expires_at": "2019-08-24T14:15:22Z"  }}
{  "code": "account_not_verifiable",  "title": "string",  "details": "string",  "challenge": {    "value": "string",    "bits": 1,    "expires_at": "2019-08-24T14:15:22Z"  }}
{  "code": "account_not_verifiable",  "title": "string",  "details": "string",  "challenge": {    "value": "string",    "bits": 1,    "expires_at": "2019-08-24T14:15:22Z"  }}
{  "code": "account_not_verifiable",  "title": "string",  "details": "string",  "challenge": {    "value": "string",    "bits": 1,    "expires_at": "2019-08-24T14:15:22Z"  }}