CustomDomain Docs
ReferenceAPI referenceProvider accounts

Connect domains with the account

Connect domains with the account: CustomDomain™ API reference in the provider accounts group. Covers parameters, request body, responses and error codes.

POST
/provider-accounts/{id}/connect

Creates a connection for each domain under its application and writes its records with the account's key (keeping the CAA and TXT values already there and recording what each write replaced).

A domain goes into the application named for it, else the call's application_id, else the application that already holds it in the workspace (its own connection's, so a domain the workspace already serves is linked where it lives). A domain none of those names answers 400, and so does one two applications hold; so does a domain named for two different applications. A call takes at most 200 domains (a domain named twice is one; 400 beyond). Every application used must be the workspace's (404 otherwise) and one the key serves, and every domain must be inside the key's scope: a call that is refused for any of this changes nothing, because all of it is checked before the first write. Each domain is linked to the account once its records are written; a domain whose write fails is not linked and keeps the access it had. A continuous account then keeps the linked domains in sync. A domain the application already serves is only linked (provider_account.relinked in the audit log), and only to a key at the provider its DNS is at whose scope already holds it; any other such domain is answered already with the reason and left as it is. A one time account deletes its key once the domains are connected, even when the caller has gone away by then, and past its hour answers 409. A domain in a zone the key does not reach fails alone (zone_not_reached on the connection); the account is flagged needs_reconnect only when the provider refuses the key itself, which is checked with a request that does not depend on the zone. A key made at a secure sign in serves its own application and the applications an admin shared it with (application_ids); naming any other application's id answers 403 (this key is not shared with this application; an admin or an owner can share it). A domain outside the key's scope answers 400, naming the domains, except for a key a member of the workspace made at a sign in started in the console (the console's signed call, not an API key that names the console): when a read of the domain's zone with the key works, the domain is connected with no new sign in, and the zone is added to the key's scope once a write there works (provider_account.domain_added in the audit log). A zone the key does not reach answers 422 zone_not_reached, naming the domains, and a provider that cannot say (a timeout, a 5xx) answers 503, never a refusal of the key: the same two answers PATCH /provider-accounts/{id} gives, with nothing written. A call reads at most 20 such zones, one read for each, and answers 400 too_many_domains_to_check before the first read beyond that; those reads are taken from the workspace's hourly budget of reach checks, and a call whose reads do not fit in what is left answers 429 reach_quota with Retry-After, with nothing read or written; PATCH /provider-accounts/{id} is the other way to widen a scope. A key an end user's secure sign-in made in the widget, or one a sign in started through the API made, answers 403: it connects domains only through that end user's own widget session. A domain the application already has, kept by such a key, is left as it is (already, not re-linked). Takes an admin, an owner or the member who connected the account. A call that connected at least one domain (its records written with the key, or a domain already serving now linked to the account) is recorded in the audit log as one provider_account.domains_connected row naming those domains, by name only, beside the provider_account.relinked and provider_account.domain_added rows it may also write; a call that connected none writes no such row. A domain already serving that was linked to this account before the call is left as it is (already), is not named in the row, and does not make one.

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/provider-accounts/string/connect" \  -H "Content-Type: application/json" \  -d '{    "domains": [      "string"    ]  }'
{  "results": [    {      "domain": "string",      "application_id": "string",      "connection_id": "string",      "status": "connected",      "message": "string"    }  ],  "account": {    "needs_you": {      "reason": "refused",      "until": "2019-08-24T14:15:22Z"    },    "health": {      "state": "ok",      "checked_at": "2019-08-24T14:15:22Z",      "failures": 0    },    "made_by": {      "how": "pasted",      "by": "string"    },    "enforced_by": "provider",    "more_domains": [      "string"    ],    "id": "string",    "kind": "api_key",    "provider": "string",    "provider_name": "string",    "label": "string",    "access": "continuous",    "scope": "all",    "domains": [      "string"    ],    "credential_held": true,    "status": "active",    "last_error": "string",    "created_by": "string",    "last_used_at": "2019-08-24T14:15:22Z",    "expires_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "connections": [      {        "id": "string",        "application_id": "string",        "domain": "string",        "status": "string"      }    ],    "uses": [      "string"    ],    "can_manage": true,    "application_id": "string",    "application_ids": [      "string"    ],    "origin": "browser_agent",    "agent_key": {      "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"      ]    },    "owner_kind": "workspace",    "end_user_ref": "string",    "account_ref": "string"  }}
{  "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": "reach_quota",  "title": "Too many checks at DNS providers this hour.",  "details": "this workspace has made as many checks of its keys at DNS providers as it may in an hour; nothing was changed, try again in about 40 minutes"}
{  "code": "account_not_verifiable",  "title": "string",  "details": "string",  "challenge": {    "value": "string",    "bits": 1,    "expires_at": "2019-08-24T14:15:22Z"  }}