Permissions

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}.