# Get Connection Shares

See who can use a shared connection when Cirra runs app actions, and what each of them may do with it.

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

Permissions: `role:manage`.

## Parameters

### Path

- `connectionId` (string, required): The connection's id, from List Connections.

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

## Example request

```bash
curl --request GET \
  --url 'https://connect.mindcloud.co/v2/connections/Cn6vH3jW8qYt/shares' \
  --header 'Authorization: Bearer $MINDCLOUD_API_TOKEN'
```

## Response fields

- `connectionId` (string): The connection (List Connections).
- `entries` (array of objects): Who may use the connection in Cirra, and how far. A member may do what any entry that matches them allows; its owner, its creator, Platform Admins and members who manage roles always have full. Empty: nothing restricts the connection yet, so every member has full. A list saved since sharing levels shipped always has one organization entry; an older list of roles alone leaves members no entry matches without access.
  - `targetType` (string): Who the entry names.
    Allowed values:
      - `organization`: Everyone in the organization. A share list has exactly one.
      - `role`: Everyone who holds one role (roleId).
      - `team`: Everyone on one team (teamId).
  - `roleId` (string): The role, for a role entry (List Roles). Null otherwise.
  - `roleName` (string): That role's name. Null for other entries, and for a role deleted since the entry was saved: such an entry matches nobody and can be removed.
  - `teamId` (string): The team, for a team entry (List Teams). Null otherwise.
  - `teamName` (string): That team's name. Null for other entries.
  - `accessLevel` (string): What the members it matches may do with the connection.
    Allowed values:
      - `none`: No access. Only on the organization entry: members no other entry matches cannot use the connection.
      - `read`: Run only actions that read data.
      - `readWrite`: Run actions that read, create, or update data.
      - `full`: Run every action, deletes included.
      - `custom`: Advanced: run what the entry's own table of record types and operations allows (permissions).
  - `permissions` (object): The Advanced table of a custom entry; null on every other level. An action runs through this entry when models[its record type][its operation] is true, else when default[its operation] is true. An action with no record type follows default; one that declares no operation is "unknown". Record types are the canonical keys of app actions (model). Grants from all the entries that match a member add up: a member may run an action when any of them allows it, so false (Blocked) only means this entry does not grant it. A table is saved in one form: record type cells equal to default are dropped, and a table with none left whose default equals a preset is saved as that preset.
    - `default` (object): Every operation, true or false: what the entry allows on record types models does not name, and on actions with no record type.
      - `read` (boolean): Actions that read records.
      - `create` (boolean): Actions that create records.
      - `update` (boolean): Actions that update records.
      - `delete` (boolean): Actions that delete records.
      - `unknown` (boolean): Actions that declare no operation ("Other").
    - `models` (object): { "<record type>": { "<operation>": true or false } }: the cells that differ from default, by canonical record type key. An operation a record type leaves out follows default.

## Example response

```json
{
  "success": true,
  "data": {
    "connectionId": "Cn6vH3jW8qYt",
    "entries": [
      {
        "targetType": "organization",
        "roleId": null,
        "roleName": null,
        "teamId": null,
        "teamName": null,
        "accessLevel": "read",
        "permissions": null
      },
      {
        "targetType": "team",
        "roleId": null,
        "roleName": null,
        "teamId": "tm_Q8dL2vN6tRwe",
        "teamName": "Finance",
        "accessLevel": "full",
        "permissions": null
      },
      {
        "targetType": "role",
        "roleId": "cr_N4pW7xK2mQs9",
        "roleName": "Accountant",
        "teamId": null,
        "teamName": null,
        "accessLevel": "custom",
        "permissions": {
          "default": {
            "read": true,
            "create": false,
            "update": false,
            "delete": false,
            "unknown": false
          },
          "models": {
            "invoice": {
              "create": true,
              "update": true
            }
          }
        }
      }
    ]
  }
}
```

## Errors

- 404 Not shared with the company (CONNECTION_NOT_SHARED): `NOT_FOUND` / `CONNECTION_NOT_SHARED` "Connection "Cn6vH3jW8qYt" is not shared with the company. Only connections shared with the company have a share list."