CustomDomain Docs
ReferenceAPI referenceProvider accounts

Every connected account, with the kept sign-ins and Domain Connect grants

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

GET
/provider-accounts

The workspace's provider accounts with their access mode, the domains they cover, when they were last used and when they expire, whether the caller may manage each one (can_manage), what needs the person (needs_you), what the last check of its key found (health), how each key was made and by whom (made_by) and who enforces its limit (enforced_by); and, in kept_access, the sign-ins and Domain Connect authorizations kept per domain, grouped by provider. A kept sign-in is stopped per domain with DELETE /connections/{id}/grant. A viewer reads them without agent_key.account (an end user's customer number at the provider), agent_key.session_id, account_ref and end_user_ref.

The accounts that need the person come first (needs_you), then the most recently used, the never used last, newest first. end_user_keys counts the keys your customers' own sign-ins made, and how many customers they belong to, so a console can show them as one row; it counts them before owner, q and paging apply.

?provider= keeps one provider's accounts. ?owner=workspace keeps the keys the workspace holds (pasted, or made at a sign-in a member started in the console); ?owner=end_user the keys your customers' own sign-ins made. ?q= keeps the accounts whose label, scope domain or linked domain holds the text, and, for a member, whose account_ref, agent_key.account or end_user_ref does; a viewer never matches those. ?limit= (1 to 200) and ?cursor= (the previous answer's next_cursor) page the list; without limit the answer holds every account. ?domain= keeps the ones that may act for that domain for the caller, best first, by the saved access resolver's rules (see GET /connections/{id}/saved-access), for ?application_id= or the API key's own application (404 for an application of another workspace), adds them as saved_access, and answers them in full: limit and cursor with it are 400.

A delegated agent token lists with domains:read (the MCP's list-provider-accounts), and sees less than an API key: only the workspace's keys that serve the application its grant is bound to, never a key an end user's own sign in made, each as a viewer reads it (no account_ref, end_user_ref, agent_key.account or agent_key.session_id), without the key's name (no agent_key.name, whichever application the key is bound to) and without who in the workspace made it (no made_by.by and no created_by; made_by.how stays), with only that application's connections and only the domains that no other application of the workspace has connected (a zone in which another application holds a domain is left out, unless the grant's own application holds one in it too), can_manage false, and an empty kept_access. application_ids is empty for every key it reads, since it names the workspace's other applications (application_id says the key serves its own). A key made for another application and shared with the grant's own one reads as <Provider> key, with no application_id (the label the agent made it with names the other application's domain), and ?q= searches what the agent reads. ?domain= answers an empty accounts and saved_access for a zone in which another application holds a domain (and the grant's own holds none), and when the workspace's connections cannot be read; it reads a key at its provider only for a zone the grant's own connections are in. ?application_id= may only repeat the grant's own application (403 otherwise). A token without domains:read is 403.

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

Query Parameters

provider?string
domain?string
application_id?string
owner?string

Whose keys to list. Without it, every account.

Value in

  • "workspace"
  • "end_user"
q?string

Text to search for in the label, the domains and, for a member, the provider account and end user ids.

limit?integer

The page size. Without it, every account.

Range1 <= value <= 200
cursor?string

The previous answer's next_cursor.

Response Body

application/json

application/json

curl -X GET "https://example.com/provider-accounts"
{  "accounts": [    {      "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"    }  ],  "kept_access": [    {      "kind": "sign_in",      "provider": "string",      "provider_name": "string",      "access": "continuous",      "connections": [        {          "id": "string",          "application_id": "string",          "domain": "string",          "status": "string"        }      ],      "created_at": "2019-08-24T14:15:22Z",      "last_used_at": "2019-08-24T14:15:22Z",      "uses": [        "string"      ]    }  ],  "keeping_available": true,  "end_user_keys": {    "keys": 0,    "end_users": 0  },  "next_cursor": "string",  "saved_access": [    {      "account_id": "string",      "provider": "string",      "provider_name": "string",      "label": "string",      "how": "api_key",      "owner_kind": "workspace",      "scope": "all",      "zone": "string",      "ready": true,      "status": "active",      "application_id": "string",      "key_name": "string",      "key_expires_at": "2019-08-24T14:15:22Z",      "last_used_at": "2019-08-24T14:15:22Z",      "from_domain": "string"    }  ]}
Empty
{  "code": "account_not_verifiable",  "title": "string",  "details": "string",  "challenge": {    "value": "string",    "bits": 1,    "expires_at": "2019-08-24T14:15:22Z"  }}
Empty
Empty