Get a connection with its authoritative record set
Get a connection with its authoritative record set: CustomDomain™ API reference in the connections group. Covers parameters, request body and responses.
Returns the connection object and its records. The connection carries a managed boolean: true when it opted in to managed mode (the control plane holds a durable, encrypted async grant so it can re-apply / revert the template server-side without re-consent); false (omitted on the wire) for the default use-once connection.
dns_hosting says who runs the domain's DNS, and reach how CustomDomain™ reaches it to write records (a kept account, a kept sign-in, one-click setup, DNS hosting, or nothing). reach is for the platform's own servers (an API key, an app-scoped token or an agent token); an end user's connect-scoped token reads dns_hosting only.
A delegated agent token needs domains:read and reads only connections of its own application; another application's connection answers 404. Its answer leaves out what the account routes leave out for it: the credential carries no account (the customer number at the provider), no session_id and no name, for any key, an end user's included, and a reach through a key made for another application reads <Provider> key as its label, since the label the agent made the key with names that application's domain. It also reads no end_user_ref, the platform's id for its end user, which the account answers leave out for it too and a connection shares with its end user's key. An API key reads all of it whole.
A widget token must be the connection's end user: a connection that names another end user than the token's end_user_ref, or names one while the token names none, answers 403 token_wrong_end_user before anything is read or changed, and a connection that names none is any token's. An API key, an app-scoped token and a delegated agent token are not limited by it.
Short-lived widget JWT minted server-side via POST /v1/tokens. Scoped to one application (and optionally one domain).
In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/connections/string"{ "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 }}{ "code": "string", "title": "string", "details": "string"}{ "code": "string", "title": "string", "details": "string"}{ "code": "string", "title": "string", "details": "string"}