# List Connections

See the connections in your company and whether they still work: shared ones and your own personal ones, each app's default first. Narrow to one app with app=slack (an app id works too), or find one by name or account email with q=sales. Under X-Company-Id the list omits Embedded end-user and installation connections. Secrets never leave the platform.

`GET https://connect.mindcloud.co/v2/connections`

Permissions: `credential:view`.

## Parameters

### Headers

- `X-Company-Id` (string): Optional. The id of the organization to act in. Leave it out to act in the API key's own organization. A key can also act in its child organizations, and, with "Use this key across all of your organizations" on, in every organization its creator can open in the app. List them with GET /v2/companies. Every response's X-Company-Id header names the organization it acted in. See [Organizations](https://mindcloud.co/docs/api/rest/introduction/organizations).

### Query

- `app` (string): An app id or slug, from List Universal Apps.
  Only this app's connections: its id or slug (slack), as List Universal Apps answers them.
- `q` (string): Part of the connection's name or of the email of the account it signed in as.
  Search text: connections whose name or signed-in account email contains it, ignoring case. * is a wildcard.

## Example request

```bash
curl --request GET \
  --url 'https://connect.mindcloud.co/v2/connections?app=slack&q=sales' \
  --header 'Authorization: Bearer $MINDCLOUD_API_TOKEN'
```

## Response fields

- `id` (string): Unique id of the connection.
- `name` (string): The connection's name, as the app lists it. Null when it was never named.
- `nameSource` (string): How the name was set. Null for connections named before this was recorded.
  Allowed values:
    - `generated`: MindCloud named it when it was created, usually after the account it signed in as.
    - `manual`: Someone typed the name.
- `appId` (string): The app this connection signs into.
- `authType` (string): How it signs in to the app, as the app's sign-in method declares it: oAuth2, oAuth1, apiKey, basic, custom, ftp or none.
- `authenticationId` (string): The app's sign-in method it uses, for an app that offers more than one.
- `accountEmail` (string): The email of the account it signed in as. Null when the app's sign-in does not report one (Slack's does not).
- `externalAccountId` (string): The signed-in account's id at the provider (a Slack workspace's team id), when the app reports one.
- `scopes` (array of string): The permissions the provider granted at sign-in. Null for a connection that is not OAuth or last signed in before MindCloud recorded them; signing it in again records them.
- `environmentId` (string): The environment it is for, when a company keeps a connection per environment.
- `status` (string): The connection's status as of statusUpdatedOn: the result of its last sign-in, test or use.
- `statusUpdatedOn` (date): When the status last changed.
- `isDefault` (boolean): True when it is the company's default connection for its app: a Universal API run that sends no connectionId uses it, and the editor picks it for a new step.
- `isCompany` (boolean): True when the whole company shares this connection.
- `owner` (string): Whose connection it is. Filter with owner[in]=company,personal to leave out Embedded end users' and installations' connections.
  Allowed values:
    - `company`: Shared with the company: usable by every member, or by who its share list names (Everyone, roles, teams).
    - `personal`: One person's: usable only by them (userId), or by who created it.
    - `endUser`: An Embedded end user's: used only on their behalf, never in a workflow step.
    - `installation`: An Embedded installation's: used only for that installation's runs.
- `usableByYou` (boolean): Whether this API key's creator may run Universal actions through it, and test or delete it: a shared connection with no share list, or whose share list gives them access (Everyone, their role or one of their teams; or they manage roles), or one of their own, the rule the Universal run applies. False for a shared connection whose share list gives them no access, and for Embedded end users' and installations' connections, which are used only on that end user's or installation's behalf. Another member's personal connection is not listed at all.
- `isGlobal` (boolean): True for a personal connection its owner can also use in every other company they belong to.
- `endUserId` (string): The embedded end user who owns it, if any.
- `installationId` (string): The embedded installation it belongs to, if any.
- `userId` (string): The user who owns it, if it is personal.
- `createdIn` (string): Where it was created: gravity (the MindCloud platform) or cirra. Null for connections created before this was recorded.
- `testedOn` (date): The last successful test.
- `expiresOn` (date): When the current sign-in expires (an OAuth access token's lifetime), if it does. MindCloud signs in again before the next use when the app allows it, so a past date on a valid connection usually means it has not been used since; status says whether that worked last time. Filter on this to catch sign-ins that cannot renew themselves.
- `authenticatedOn` (date): The last time someone authenticated it.
- `attemptedOn` (date): The last time someone started signing it in, whether or not they finished.
- `createdOn` (date): When the connection was created.
- `createdBy` (string): Who created it: a member's userId (List Members), or an embedded end user's id. With createdOn and authenticatedOn, this tells apart connections that share a name, such as several to the same Slack workspace.
- `updatedOn` (date): When it was last changed.
- `updatedBy` (string): Who last changed it.