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

# Permissions

> List available permissions and resolve effective permissions for the current user.

The Permissions API provides fine-grained RBAC capabilities beyond the base roles (viewer, editor, admin). It supports custom roles with specific permission sets.

## GET /api/v1/permissions

List all available permissions or resolve the current user's effective permissions.

**Roles:** viewer, editor, admin (minimum `viewer`)

### Query Parameters

| Parameter | Type   | Required | Description                                                                                      |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `action`  | string | No       | `list` to list all permissions, `resolve` to get current user's permissions (default: `resolve`) |

### Response — `resolve`

```json theme={null}
{
  "role": "editor",
  "userId": "user_abc123",
  "permissions": [
    "offers.read",
    "offers.write",
    "channels.read",
    "channels.write",
    "decision_flows.read",
    "decision_flows.write"
  ],
  "totalPermissions": 6
}
```

### Response — `list`

```json theme={null}
{
  "permissions": [
    "offers.read",
    "offers.write",
    "offers.delete",
    "channels.read",
    "channels.write",
    "decision_flows.read",
    "decision_flows.write",
    "decision_flows.publish",
    "users.manage",
    "settings.manage"
  ]
}
```

***

## POST /api/v1/permissions

Assign a custom role to a user. **Admin only.**

### Request Body

| Field    | Type   | Required | Description                   |
| -------- | ------ | -------- | ----------------------------- |
| `userId` | string | Yes      | User ID to assign the role to |
| `roleId` | string | Yes      | Custom role ID                |

### Response (201)

```json theme={null}
{
  "id": "clx...",
  "userId": "user_abc123",
  "roleId": "role_marketing_editor",
  "tenantId": "my-tenant"
}
```