# 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
unkey api permissions set-role-permissions [flags]
```

## Flags

<ParamField body="--role-id" type="string" required>
The ID or slug of the role whose directly assigned permissions will be replaced.
</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
unkey api permissions set-role-permissions \
  --role-id=role_1234abcd \
  --permissions=documents.read,documents.write
```
```bash Clear permissions
unkey api permissions set-role-permissions \
  --role-id=role_1234abcd \
  --permissions=
```
</CodeGroup>

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