Permissions
ScaiQueue has two layers of access:
- four tenant-wide module-permission keys, mapped onto ScaiGrid's RBAC system;
- scope roles (
owner,operator,producer,consumer,viewer) that apply to one scope. See Scopes as realms.
Every endpoint checks one capability on the scope it touches. A caller has it through tenant-wide permissions (on unrestricted scopes), through a scope role, or by being a tenant admin. All endpoints also require a tenant-scoped caller.
Permission keys#
| Key | What it grants |
|---|---|
scaiqueue:view |
On unrestricted scopes: list and read scopes, queues, messages, routing rules, streams, subscriptions, schemas, HITL patterns, audit log; system-agent status. |
scaiqueue:publish |
On unrestricted scopes: publish messages. |
scaiqueue:consume |
On unrestricted scopes: claim, complete, fail, release, extend messages; create subscriptions; check subscription dedup. |
scaiqueue:create_scopes |
Create scopes and become their owner; archive, unarchive and delete scopes it owns. No access to other scopes, and not tenant level. For services that provision their own realms. |
scaiqueue:manage |
Tenant-level ScaiQueue admin: everything in every scope of the tenant, restricted or not, plus creating, archiving and deleting scopes, restricting them, and GDPR jobs. |
Scope roles#
| Role | Capabilities in that scope |
|---|---|
owner |
view, publish, consume, operate, and manage access (grants, queue ACL, trusted scopes) |
operator |
view, publish, consume, operate (queues, routing rules, schemas, HITL patterns, subscriptions, cancel messages, pause/resume/drain the scope) |
producer |
view, publish |
consumer |
view, consume |
viewer |
view |
Grant them with POST /scopes/{scope_id}/acl/grants. Callers with only scope roles need no tenant-wide ScaiQueue permission.
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:
1 2 3 4 5 6 7 | |
1 2 3 4 5 6 7 | |
Reserve scaiqueue:manage for the small group that runs queue infrastructure. To let a team or service run its own queues, give it a scope role instead (operator or owner) rather than tenant-wide scaiqueue:manage.
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}.