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"