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

ScaiQueue defines four module-permission keys, mapped onto ScaiGrid's RBAC system. Every endpoint enforces one of them, and all endpoints additionally require the caller to be tenant-scoped.

## Permission keys

| Key | What it grants |
|---|---|
| `scaiqueue:view` | List and read scopes, queues, messages, routing rules, streams, subscriptions, schemas, HITL patterns, audit log, system-agent status. |
| `scaiqueue:publish` | Publish messages into queues the caller can see. |
| `scaiqueue:consume` | Claim, complete, fail, release, extend messages; create subscriptions; check subscription dedup. |
| `scaiqueue:manage` | Create and delete scopes and queues, change scope and queue lifecycle, manage routing rules, schemas, HITL patterns, ACL grants, queue ACL entries, cross-scope trusts, API keys, and GDPR jobs. |

## Default role mapping

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

| Role | Auto-grants |
|---|---|
| `super_admin` | All four (but still needs a tenant_id on the token to use the endpoints). |
| `partner_admin` | All four for tenants under the partner. |
| `tenant_admin` | All four for the tenant. |
| `tenant_user` | None by default. |
| `tenant_viewer` | `scaiqueue:view`. |

`tenant_user` gets nothing automatically because publishing and consuming both have real cost and observability implications — grant them explicitly.

## Granting selectively

A typical pattern is one role for producer-agents and one for consumer-agents:

```bash
curl -X POST "$SCAIGRID_HOST/v1/iam/custom-roles" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Queue producers",
    "module_permissions": ["scaiqueue:view", "scaiqueue:publish"]
  }'
```

```bash
curl -X POST "$SCAIGRID_HOST/v1/iam/custom-roles" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Queue consumers",
    "module_permissions": ["scaiqueue:view", "scaiqueue:consume"]
  }'
```

Reserve `scaiqueue:manage` for the small group that runs queue infrastructure — they create scopes, set routing rules, manage ACLs, and rotate API keys.

## Audit

Every permission-gated call is recorded in the ScaiQueue audit log. Query by scope, event type, actor id, or correlation id via `GET /scopes/{scope_id}/audit`. Full per-chain traces are at `GET /scopes/{scope_id}/audit/trace/{correlation_id}`.