Change a domain's client name, www redirect or forwarding

Change a domain's client name, www redirect or forwarding: CustomDomain™ API reference in the connections group. Covers parameters, request body and responses.

Changes the settings of a domain a person edits after it is set up: client_label (the name of the client it is for), www_redirect (a root domain's redirect to www) and redirect_to (forward every visit to another site). Send only what changes. A body that changes nothing answers 200 and writes nothing.

Who may call it. A server side credential only: an API key of a member who may change domains (member, admin or owner; a viewer's key is 403), or an app-scoped token for a connection of its own application. An end user's connect-scoped widget token is refused 403, its own connection included, and so is a delegated agent token: the name, the www redirect and above all the forward decide where the domain's visitors go, so the platform that owns the domain decides, not the person connecting it or an agent acting for them. A connection of another workspace answers 404.

A test mode domain takes client_label only (403 sandbox_not_allowed for the redirects).

The www redirect changes the records the domain needs. A zone we host is rewritten at once; a domain whose records were written through a connected provider account is rewritten when move_rewrite is on; any other domain is reported with connection.records_outdated and the answer's customer_action_required is true when a record was added. A live domain stays live while that record is missing.

Forwarding is held to one validator, the same one POST /connections/{id}/power and /power:repower use for their redirect_to: see redirect_to in the body. A value equal to the one stored is not checked again.

Every change is recorded in the audit log as connection.updated, with the before and after of the fields that changed, by the member or key that made it (widget:<application id> for an app-scoped token).

Two requests at once. Redirect changes of one workspace are made one at a time, each checked against the domains as they are when its turn comes, so two changes made together cannot make a circle between them: the second is refused (422 redirect_loop). A change that waits too long for its turn answers 503 redirects_busy (Retry-After) and changes nothing. A request writes only the settings it changes, and a value it sends back as it read it is not a change, so a setting another request has changed since is not undone.

When something fails. The redirects are stored before the name. When client_label is sent with www_redirect or redirect_to and only the name cannot be written, the answer is 500, the redirect change is stored and is in the audit log, and sending the same body again writes the name.

Authorization

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

TypeScript Definitions

Use the request body type in TypeScript.

The settings of a domain PATCH /connections/{id} changes. Every field is optional and a field left out is unchanged; at least one is required. The body is decoded with unknown fields REJECTED, so the properties below are exactly the accepted set.

client_label?string

The name of the client or customer the domain is for. Characters that draw nothing (a right to left override, a zero width space, the blank fillers, variation selectors, private use characters) are dropped, control characters and runs of white space become one space, and the name is trimmed. Only "" clears it: a value that is not empty but has nothing readable left (white space, or only invisible characters) is 400, so it cannot take a name off. More than 200 characters is 400.

Lengthlength <= 200

www_redirect?boolean

Send visitors of the root domain (acme.com) to www.acme.com. Root domains only: true on a subdomain is 422 www_redirect_apex_only. Available on every plan. Turning it on adds a www record to the records the domain needs; turning it off takes it out, and the edge then answers for www.acme.com only if you connected it as its own domain. Not for a test mode domain (403 sandbox_not_allowed).

redirect_to?string

Where the edge sends every visit to the domain (a 301, keeping the visit's path and query): a plain https:// address of a public domain, "" to clear it. It needs edge serving, which comes with Growth and up: 402 plan_upgrade_required on a plan without it and 503 where the deployment has it off (clearing a forward needs neither). 400 for an address that is not https (http:, javascript:, data:, a scheme-less address), has a username or password (https://[email protected]), names an IP address, a name with no dot or a reserved name (localhost, .local, .internal, .test), or contains spaces, backslashes or hidden characters. The port is read as a number and stored once: :443 is dropped and a leading zero is not kept (:0443 is 443), and a target that names this domain on port 80 or 443 is the domain itself, as the edge reads it. 422 redirect_target_not_allowed for a domain another workspace has connected or claimed (unless your own workspace serves it), and 422 redirect_loop when the target is the domain itself or a visit would come back to a host it has been through, through this domain's www redirect or any forward of your own domains, or goes through more than 8 forwards in a row. Not for a test mode domain.

Lengthlength <= 2048

Response Body

`application/json`

curl -X PATCH "https://example.com/connections/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "application_id": "string",  "domain": "string",  "host": "string",  "provider_id": "string",  "setup_type": "automatic",  "status": "pending",  "managed": true,  "created_at": "2019-08-24T14:15:22Z",  "sandbox": true,  "last_checked_at": "2019-08-24T14:15:22Z",  "www_redirect": true,  "override_spf": true,  "validate_dmarc": true,  "validate_caa": true,  "monitor": true,  "batch_id": "string",  "end_user_ref": "string",  "client_label": "string",  "retried_at": "2019-08-24T14:15:22Z",  "routing": {    "mode": "edge",    "cname_target": "string",    "apex_ipv4": [      "string"    ],    "set_at": "2019-08-24T14:15:22Z"  },  "records_source": "integrator",  "created_via": "",  "secure_root_domain": true,  "redirect_to": "http://example.com",  "power_root_path_access": [    "string"  ],  "error_code": "string",  "error_message": "string",  "write_rail": "api_key",  "provider_account_id": "string",  "removal_started_at": "2019-08-24T14:15:22Z",  "dns_hosting": {    "state": "none",    "by": "customdomain",    "provider": "string",    "zone": "string",    "since": "2019-08-24T14:15:22Z"  },  "records": [    {      "type": "CNAME",      "host": "string",      "value": "string",      "ttl": 3600,      "priority": 0,      "applied": true,      "change": "created",      "prior": [        {          "type": "string",          "value": "string",          "ttl": 0,          "priority": 0        }      ],      "prior_source": "provider"    }  ],  "end_user_email": "[email protected]",  "ask_end_user_email": true,  "credential": {    "account_id": "string",    "provider": "string",    "status": "active",    "name": "string",    "scopes": [      "string"    ],    "account": "string",    "session_id": "string",    "verified_at": "2019-08-24T14:15:22Z",    "expires_at": "2019-08-24T14:15:22Z",    "notice": "d30",    "reconnect_reason": "expiring",    "reconnect_sent_at": "2019-08-24T14:15:22Z",    "renewed_at": "2019-08-24T14:15:22Z",    "old_key": "revoke_by_hand",    "revoke_url": "http://example.com",    "rights": [      "transfer"    ]  },  "reach": {    "kind": "account",    "account_id": "string",    "label": "string",    "provider": "string",    "can_reapply": true,    "managed_possible": true  },  "customer_action_required": true}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

Change a domain's client name, www redirect or forwarding

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

402application/json

403application/json

404application/json

409application/json

422application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`