Permissions

ScaiMatrix uses a two-layer model. Module permissions gate API access at the coarsest level — they decide whether a caller can hit the endpoints at all. Per-resource ACLs (covered in ACLs) decide whether a specific call against a specific collection or document succeeds. A caller needs both.

Module permission keys#

Key	Grants
`scaimatrix:view`	List collections, read collection / document metadata, view graph views, view re-chunk and re-extract status.
`scaimatrix:search`	Run vector, hybrid, and combined searches; run graph queries, traversals, paths, ask, context, search.
`scaimatrix:ingest`	Upload documents, ingest-from-URL, ingest-from-ScaiDrive, run crawls. Subject to per-resource `INGEST` on the target collection.
`scaimatrix:manage`	Create, update, delete collections; fork; re-chunk; re-extract; manage crawl configs.
`scaimatrix:graph_edit`	Create, update, delete graph nodes and edges; bulk-import graphs.
`scaimatrix:access`	Read and modify ACLs (any endpoint under `/permissions/...` and legacy `/access`).

Default role mapping#

ScaiGrid's built-in roles auto-grant the module permissions via CurrentUser.has_module_permission:

Role	Auto-grants
`super_admin`	All of the above, across every tenant.
`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.
`tenant_viewer`	`scaimatrix:view`, `scaimatrix:search`.

tenant_user gets nothing automatically because indexing burns budget and ACL administration has compliance implications — you want explicit opt-in.

Granting selectively#

Most tenants define a single custom role for engineers maintaining knowledge bases:

bash
curl -X POST "$SCAIGRID_HOST/v1/iam/custom-roles" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Knowledge editors",
    "module_permissions": [
      "scaimatrix:view",
      "scaimatrix:search",
      "scaimatrix:ingest",
      "scaimatrix:graph_edit"
    ]
  }'

A separate "Knowledge admins" role with scaimatrix:manage and scaimatrix:access is held by fewer people.

How module perms compose with ACLs#

The two layers run in series:

Module permission is checked at the route boundary by ScaiGrid's RBAC system.
Per-resource ACE is checked by AclResolver.can(user, ref, Permission.X) against the target collection or document.

A user with scaimatrix:search but no READ ACE on any collection sees an empty list — the endpoints don't 403, they return zero rows. That's deliberate: it stops permission probes from leaking which collections exist.

A user with scaimatrix:manage cannot manage a specific collection if they lack MANAGER on its ACL — the role gets you to the endpoint, the ACL decides what happens there.

Bypasses#

Three principals skip ACL checks regardless of ACEs:

SUPER_ADMIN — global, all tenants.
TENANT_ADMIN — every resource in their tenant.
Resource owner — the resource they own, even against explicit denies.

Owners and admins still need the relevant module permission, e.g. a tenant admin without scaimatrix:view can't see ScaiMatrix at all.

Audit#

Every ACL mutation and ownership transfer is logged through ScaiGrid's audit pipeline. Filter with module=scaimatrix:

bash
curl "$SCAIGRID_HOST/v1/audit/events?module=scaimatrix&since=2026-05-01" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY"

Graph mutations (node.created, edge.deleted, import.completed, reextract.queued) and ACL changes (ownership.transferred) appear here with actor_user_id, resource_type, resource_id, and a details payload.