# 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.

Source: https://docs.customdomain.ai/docs/api-reference/provider-accounts/listProviderAccounts

## `GET https://api.customdomain.ai/v1/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`.

### Authentication

`apiKey`, `agentToken`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `provider` | query | string | no |  |
| `domain` | query | string | no |  |
| `application_id` | query | string | no |  |
| `owner` | query | `workspace`, `end_user` | no | Whose keys to list. Without it, every account. |
| `q` | query | string | no | Text to search for in the label, the domains and, for a member, the provider account and end user ids. |
| `limit` | query | integer | no | The page size. Without it, every account. |
| `cursor` | query | string | no | The previous answer's `next_cursor`. |

### Responses

| Status | Description |
| --- | --- |
| `200` | The accounts |
| `400` | `owner` is not `workspace` or `end_user`, `limit` is not a whole number from 1 to 200, `cursor` is not one this endpoint returned, or `limit` or `cursor` with `?domain=` |
| `401` | Error envelope: {code, title, details}. |
| `403` | An agent token without `domains:read`, or `?application_id=` naming another application than the agent grant's |
| `404` | `?domain=` with an `application_id` (or an API key's own application) of another workspace, or none |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accounts` | array of object | yes |  |
| `kept_access` | array of object | yes |  |
| `keeping_available` | boolean | yes | Whether keys can be kept. |
| `end_user_keys` | object | no | The keys your customers' own sign-ins made (`owner_kind` `end_user`), counted before `owner`, `q` and paging apply, so a console can show them as one row. |
| `next_cursor` | string | no | With `?limit=` only, when more accounts remain. Send it as `?cursor=` for the next page. |
| `saved_access` | array of object | no | With `?domain=` only. The keys that may act for the domain for the caller, best first, as `GET /connections/{id}/saved-access` lists them. |

The full specification is served at `GET https://api.customdomain.ai/v1/openapi.json`.
