# Roles

> Role and permission management API

Source: https://docs.soosh.io/reference/api/roles/

> **Careful:** Role management endpoints require the `roles:read`, `roles:write`, or `roles:delete` permission. There is no separate create/update action — creating and editing both use `roles:write`.

## Overview

Manage roles and permissions within your organization. Roles are collections of permissions that can be assigned to users.

## List Permissions

Get the permission catalog for the active organization. It lists only permissions of components the workspace has (plus the governance permissions every workspace has); platform permissions are never listed. Each entry includes `key`, `module` and `module_label` (the section of the component the permission belongs to), `available` (always `true`; kept for older clients) and `grantable` (whether you hold it and can give it), in addition to its resource and action.

`GET /api/permissions`

### Response

```json
{
  "status": "success",
  "data": {
    "permissions": [
      {
        "id": "uuid",
        "resource": "users",
        "action": "read",
        "description": "View users"
      },
      {
        "id": "uuid",
        "resource": "users",
        "action": "write",
        "description": "Create and edit users"
      }
    ]
  }
}
```

## List Roles

Get all roles in your organization.

`GET /api/roles`

> **Note:** Requires `roles:read` permission.

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `search` | string | Filter by role name |

### Response

```json
{
  "status": "success",
  "data": {
    "roles": [
      {
        "id": "uuid",
        "name": "admin",
        "description": "Full access to all features",
        "is_system": true,
        "is_default": false,
        "version": 4,
        "feature_version": 7,
        "permissions": ["users:read", "users:write", "users:delete"],
        "inactive_permission_count": 0,
        "user_count": 3,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      },
      {
        "id": "uuid",
        "name": "Custom Role",
        "description": "Custom role with specific permissions",
        "is_system": false,
        "is_default": false,
        "version": 2,
        "feature_version": 7,
        "permissions": ["chat:read", "chat:write"],
        "inactive_permission_count": 1,
        "user_count": 8,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 4,
    "page": 1,
    "limit": 50
  }
}
```

`permissions` is a flat array of `resource:action` strings on the workspace's components, and `user_count` is how many users hold
the role in this organization. Responses include the current `version`, the workspace's
`feature_version`, and `inactive_permission_count`: saved grants on components the workspace
doesn't have, which aren't listed and give no access. There is no `permission_count` field.

## Get Role

Get a single role with its permissions.

`GET /api/roles/{id}`

### Response

```json
{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Custom Role",
    "description": "Custom role with specific permissions",
    "is_system": false,
    "is_default": false,
    "version": 1,
    "feature_version": 7,
    "permissions": ["contacts:read", "contacts:write"],
    "inactive_permission_count": 0,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

## Create Role

Create a new custom role.

`POST /api/roles`

> **Note:** Requires `roles:write` permission.

### Request Body

```json
{
  "name": "Support Agent",
  "description": "Can view and respond to chats",
  "permissions": ["contacts:read", "chat:read", "chat:write"]
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Unique role name |
| `description` | string | No | Role description |
| `permissions` | array | Yes | Array of permission keys (e.g., `resource:action`) |
| `is_default` | boolean | No | Set as default role for new users |

### Response

```json
{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Support Agent",
    "description": "Can view and respond to chats",
    "is_system": false,
    "is_default": false,
    "version": 1,
    "feature_version": 7,
    "permissions": ["contacts:read", "chat:read", "chat:write"],
    "inactive_permission_count": 0,
    "created_at": "2024-01-01T00:00:00Z"
  }
}
```

## Update Role

Update an existing custom role.

`PUT /api/roles/{id}`

> **Note:** Requires `roles:write` permission.

> **Careful:** System role names and default flags are fixed. Only platform super administrators can edit their permission grants; authorized role administrators can edit descriptions.

### Request Body

```json
{
  "name": "Senior Support Agent",
  "version": 1,
  "feature_version": 7,
  "description": "Can view, respond to chats, and access analytics",
  "permissions": ["contacts:read", "chat:read", "chat:write", "analytics:read"]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Role name |
| `description` | string | Role description |
| `permissions` | array | Array of permission keys |
| `is_default` | boolean | Set as default role for new users |
| `version` | integer | Required current version from the role response; stale edits return `409` |
| `feature_version` | integer | `feature_version` from the role response. Required when sending any `permissions` value (including `[]`) or `remove_inactive_permissions: true`; `400` without it. Optional for metadata-only saves. A save that sends a stale `feature_version` (the workspace's components changed since) returns `409` |
| `remove_inactive_permissions` | boolean | Removes the role's saved grants on components the workspace doesn't have. You must hold each one; platform grants are never removed |

### Response

```json
{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Senior Support Agent",
    "description": "Can view, respond to chats, and access analytics",
    "is_system": false,
    "is_default": false,
    "version": 2,
    "feature_version": 7,
    "permissions": [...],
    "inactive_permission_count": 0,
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

Omitting `permissions` preserves the current grants. `permissions` is the role's grants on the
workspace's components: sending an empty array clears those. Grants on components the workspace
doesn't have (and platform grants) aren't listed and are kept as saved; they give no access until
the component is added, unless you send `remove_inactive_permissions: true`. Unknown keys are rejected, and new grants on components the workspace
doesn't have return `403`. Editors can only grant or remove permissions they hold among the
listed ones; a saved grant on a missing component doesn't stop them editing the rest.
Metadata and grants save atomically. A tenant administrator cannot edit their own role,
and changes cannot remove an organization's last active administrator.

## Delete Role

Delete a custom role.

`DELETE /api/roles/{id}`

> **Note:** Requires `roles:delete` permission.

> **Careful:** - System roles cannot be deleted
> - Roles with assigned users cannot be deleted (reassign users first)

### Response

```json
{
  "status": "success",
  "data": {
    "message": "Role deleted successfully"
  }
}
```

## Permission Keys

Permissions use the format `resource:action`. The only valid actions are:
`read`, `write`, `delete`, `sync`, `execute`, `import`, `export`, `pickup`, and `assign`.

> **Careful:** There is **no** `create` or `update` action. Creating and editing both map to `write`.

The full catalog below matches the permissions seeded on every organization.

### Users, Roles & Teams
- `users:read`, `users:write`, `users:delete`
- `roles:read`, `roles:write`, `roles:delete`
- `teams:read`, `teams:write`, `teams:delete`

### Settings
- `settings.general:read`, `settings.general:write`
- `settings.calling:read`, `settings.calling:write`
- `settings.chatbot:read`, `settings.chatbot:write`
- `chatbot.routing:read`, `chatbot.routing:write`
- `chatbot.hours:read`, `chatbot.hours:write`
- `chatbot.sla:read`, `chatbot.sla:write`

### WhatsApp Accounts, Templates & Flows
- `accounts:read`, `accounts:write`, `accounts:delete`
- `catalogs:read`, `catalogs:write`, `catalogs:delete`
- `templates:read`, `templates:write`, `templates:delete`, `templates:sync`
- `flows.whatsapp:read`, `flows.whatsapp:write`, `flows.whatsapp:delete`
- `flows.chatbot:read`, `flows.chatbot:write`, `flows.chatbot:delete`

### Chatbot
- `chatbot.keywords:read`, `chatbot.keywords:write`, `chatbot.keywords:delete`
- `chatbot.ai:read`, `chatbot.ai:write`, `chatbot.ai:delete`
- `chatbot.memory:read`, `chatbot.memory:write`

### Chat & Contacts
- `chat:read`, `chat:write`, `chat.assign:write`
- `contacts:read`, `contacts:write`, `contacts:delete`, `contacts:import`, `contacts:export`
- `tags:read`, `tags:write`, `tags:delete`, `tags:import`, `tags:export`
- `transfers:read`, `transfers:write`, `transfers:pickup`
- `canned_responses:read`, `canned_responses:write`, `canned_responses:delete`

### Campaigns
- `campaigns:read`, `campaigns:write`, `campaigns:delete`, `campaigns:execute`

### Analytics & Audit
- `analytics:read`, `analytics:write`, `analytics:delete`, `analytics.agents:read`
- `audit_logs:read`

### Integrations
- `webhooks:read`, `webhooks:write`, `webhooks:delete`
- `api_keys:read`, `api_keys:write`, `api_keys:delete`
- `custom_actions:read`, `custom_actions:write`, `custom_actions:delete`

### Organizations
- `organizations:read`, `organizations:assign` (tenant member visibility and assignment)

### Calling
- `call_logs:read`
- `ivr_flows:read`, `ivr_flows:write`, `ivr_flows:delete`
- `call_transfers:read`, `call_transfers:write`
- `outgoing_calls:read`, `outgoing_calls:write`

Platform SSO, organization creation, WhatsApp app and webhook-inbox administration require a platform super administrator. Legacy `settings.sso` and organization `write`/`delete` grants are reserved and cannot be delegated through tenant roles.

## See Also

- [Roles & Permissions](https://docs.soosh.io/features/roles-permissions) - Learn about the permission system
- [Users API](https://docs.soosh.io/reference/api/users) - User management