---
summary: ScaiBot module permissions and which roles get them by default.
title: Permissions
path: reference/permissions
status: published
---

# Permissions

ScaiBot defines its own module-permission keys, mapped onto ScaiGrid's RBAC system. Every endpoint enforces one of them.

## Permission keys

| Key | What it grants |
|---|---|
| `scaibot:bots:read` | List bots, read bot config, read tone, list escalation rules, list documents, view embed info. |
| `scaibot:bots:create` | Create new bots. |
| `scaibot:bots:update` | Modify bot config and tone, change lifecycle status. |
| `scaibot:bots:delete` | Delete bots. |
| `scaibot:knowledge:manage` | Upload, replace, delete documents (managed mode) or change `knowledge_collection_id` (linked mode). |
| `scaibot:conversations:read` | List and read conversations; includes seeing system prompts via `include_system_prompt=true`. |
| `scaibot:conversations:manage` | Close conversations, edit retention. |
| `scaibot:escalations:manage` | Create, update, delete, and reorder escalation rules. |
| `scaibot:embed:issue` | Mint embed tokens (`POST /bots/{id}/embed-token`). |
| `scaibot:embed:revoke` | Revoke active embed tokens. |

## Default role mapping

Built-in roles auto-grant these via ScaiGrid's catch-all in `CurrentUser.has_module_permission`:

| Role | Auto-grants |
|---|---|
| `super_admin` | All of the above. |
| `partner_admin` | All of the above for tenants under the partner. |
| `tenant_admin` | All of the above for the tenant. |
| `tenant_user` | None by default (see below). |
| `tenant_viewer` | `scaibot:bots:read`, `scaibot:conversations:read`. |

`tenant_user` gets nothing automatically because a chat product affects accounting and the brand voice — you want explicit opt-in.

## Granting selectively

Most tenants use a single custom role for engineers who maintain bots:

```bash
curl -X POST "$SCAIGRID_HOST/v1/iam/custom-roles" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bot operators",
    "module_permissions": [
      "scaibot:bots:read",
      "scaibot:bots:update",
      "scaibot:knowledge:manage",
      "scaibot:escalations:manage",
      "scaibot:embed:issue",
      "scaibot:conversations:read"
    ]
  }'
```

Then map a group to that role. A separate "Bot creators" role with `scaibot:bots:create` is usually held by fewer people.

## Embed tokens vs. user permissions

The widget never carries a user permission. The embed token grants exactly one capability: chat with this specific bot, as this specific (optional) visitor identity, until the TTL expires. It cannot list bots, read other conversations, or do anything outside the chat endpoint.

## Audit

Every permission-gated call is logged with `actor_user_id`, `action`, `resource_id`. ScaiGrid's audit log query supports filtering by `module = "scaibot"`:

```bash
curl "$SCAIGRID_HOST/v1/audit/events?module=scaibot&since=2026-04-15" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY"
```