# Update Connection Shares Choose who can use a shared connection in Cirra and what they may do with it: everyone in the organization, roles, and teams, each at its own access level. `PUT 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). ### Body - `entries` (array, required): The whole new share list, replacing the current one. Exactly one organization entry; role entries take roleId (List Roles), team entries teamId (List Teams). Entries read from Get Connection Shares can be sent back without roleName and teamName, which are read-only. The whole new share list. It replaces the current one: an entry left out is removed. Exactly one organization entry; at most one entry per role or team. - `targetType` (string, required): 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, from List Roles. Required on a role entry; null or left out on the others. - `teamId` (string): The team, from List Teams. Required on a team entry; null or left out on the others. - `accessLevel` (string, required): What the members the entry matches may do with the connection. none is only for the organization entry. 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): Required on a custom entry; null or left out on the others. 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, required): 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, required): Actions that read records. - `create` (boolean, required): Actions that create records. - `update` (boolean, required): Actions that update records. - `delete` (boolean, required): Actions that delete records. - `unknown` (boolean, required): Actions that declare no operation ("Other"). - `models` (object, required): { "": { "": true or false } }: the cells that differ from default, by canonical record type key. An operation a record type leaves out follows default. ## Example request ```bash curl --request PUT \ --url 'https://connect.mindcloud.co/v2/connections/Cn6vH3jW8qYt/shares' \ --header 'Authorization: Bearer $MINDCLOUD_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "entries": [ { "targetType": "organization", "accessLevel": "read" }, { "targetType": "team", "teamId": "tm_Q8dL2vN6tRwe", "accessLevel": "full" } ] }' ``` ## 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): { "": { "": true or false } }: the cells that differ from default, by canonical record type key. An operation a record type leaves out follows default. ## Errors - 400 Unknown role or team (CONNECTION_SHARE_TARGET_UNKNOWN): `VALIDATION_FAILED` / `CONNECTION_SHARE_TARGET_UNKNOWN` "These roles or teams are not available to the company: tm_elsewhere. Use GET /v2/roles and GET /v2/teams." - 400 A team or role table that allows nothing (CONNECTION_SHARE_NO_ACCESS): `VALIDATION_FAILED` / `CONNECTION_SHARE_NO_ACCESS` "An Advanced table for a team or role must allow something. Remove the entry to give it no access of its own." - 403 Another organization (PARENT_DELEGATE_FORBIDDEN): `FORBIDDEN` / `PARENT_DELEGATE_FORBIDDEN` "Only a key of this organization can change who may use its connections." - 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."