> ## Documentation Index
> Fetch the complete documentation index at: https://unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# set-role-permissions

> Replace all permissions directly assigned to a role

Atomically replace all permissions directly assigned to a role. An empty `permissions` array removes every permission from the role. Permissions that don't exist are created when the caller has permission to create them.

**Required permissions:**

* `rbac.*.add_permission_to_role`
* `rbac.*.remove_permission_from_role`

Creating a missing permission also requires `rbac.*.create_permission`.

## Usage

```bash theme={"theme":"kanagawa-wave"}
unkey api permissions set-role-permissions [flags]
```

## Flags

<ParamField body="--role" type="string">
  The generated role ID or unique role name whose directly assigned permissions will be replaced. Set exactly one of `--role` or `--role-id`.
</ParamField>

<ParamField body="--role-id" type="string">
  Deprecated. Use `--role` instead. Accepts a generated role ID or unique role name.
</ParamField>

<ParamField body="--permissions" type="string[]" required>
  The complete set of permission slugs to assign directly to the role. Separate multiple values with commas. Missing permissions are created when authorized. Pass an empty value to clear all direct permissions.
</ParamField>

## Global Flags

| Flag         | Type   | Description                                                                                   |
| ------------ | ------ | --------------------------------------------------------------------------------------------- |
| `--root-key` | string | Override root key (`$UNKEY_ROOT_KEY`)                                                         |
| `--api-url`  | string | Override API base URL (default: `https://api.unkey.com`)                                      |
| `--config`   | string | Path to config file (default: `~/.unkey/config.toml`)                                         |
| `--output`   | string | Output format. Use `json` for raw JSON                                                        |
| `--body`     | string | Send this JSON string as the request body. You cannot combine it with request-building flags. |

## Examples

<CodeGroup>
  ```bash Set permissions theme={"theme":"kanagawa-wave"}
  unkey api permissions set-role-permissions \
    --role=admin \
    --permissions=documents.read,documents.write
  ```

  ```bash Clear permissions theme={"theme":"kanagawa-wave"}
  unkey api permissions set-role-permissions \
    --role-id=role_1234abcd \
    --permissions=
  ```
</CodeGroup>

<Note>
  See [Roles and permissions](/docs/platform/apis/features/authorization/roles-and-permissions)
  for RBAC concepts and examples.
</Note>