# Update Role Capabilities

Allow or deny what a role's members may do in Cirra, down to a single app action. To restrict one person, give them a role that denies it.

`PUT https://connect.mindcloud.co/v2/roles/:roleId/capabilities`

Permissions: `role:manage`.

## Parameters

### Path

- `roleId` (string, required): The role's id, from List Roles.

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

- `capabilities` (object, required): Keys to set, each to allow, deny, or null to clear.
  { capabilityKey: value }: allow, deny, or null to clear the rule so the key follows its fallback. Keys come from Get Capability Catalog.

## Example request

```bash
curl --request PUT \
  --url 'https://connect.mindcloud.co/v2/roles/Rl5wB9cF3hJp/capabilities' \
  --header 'Authorization: Bearer $MINDCLOUD_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "capabilities": {
    "webSearch": "deny",
    "apps.salesforce.actions.delete-contact": "deny",
    "apps.default.delete": null
  }
}'
```

## Response fields

- `roleId` (string): The role.
- `capabilities` (array of objects): Every rule the role sets, in key order. A key it does not set follows its fallback (Get Capability Catalog).
  - `key` (string): The capability key, such as apps.salesforce.contact.delete.
  - `value` (string): allow or deny. A deny is a ceiling no member of the role can lift.
    Allowed values:
      - `allow`
      - `deny`

## Errors

- 403 Role beyond the key: `FORBIDDEN` / `ROLE_CAPABILITIES_EXCEED_ACTOR` "You can change the Cirra rules only of a role whose permissions you hold. This role also grants: company:delete."