Roles and Permissions

ScaiGrid authorization is permission-based. Roles are bundles of permissions. Users get roles; endpoints check permissions.

Built-in roles#

Six roles ship out of the box, covering the common hierarchy:

Permission bundles (from lowest to highest):

tenant_viewer — models:list, accounting:view_own.

tenant_user — tenant_viewer permissions plus models:use, api_keys:manage, modules:use.

tenant_admin — tenant_user permissions plus routing:view, accounting:view_tenant, accounting:manage_budgets, users:manage, webhooks:manage, modules:manage, admin:access.

partner_viewer — models:list, accounting:view_own, accounting:view_tenant, accounting:view_partner.

partner_admin — partner_viewer permissions plus accounting:manage_budgets, users:manage, admin:access.

super_admin — every permission, all the time, platform-wide.

Core permissions#

The 15 core permissions ScaiGrid uses internally:

Module permissions#

Modules register their own permissions. They follow the convention {module_id}:{action} and are stored on the user as a separate set from core IAM permissions. A few representative examples:

• scaibot:manage — manage chatbot configurations
• scaimatrix:ingest — add documents to a knowledge collection
• scaibunker:execute — run commands inside a sandbox
• scaibunker:admin:tenant — manage tenant-scoped quota profiles + assignments
• scaiqueue:publish — send messages to a queue

ScaiBunker has the most granular permission set in the platform — covering bunker creation, lifecycle modes, network profiles, image management, and tiered admin levels (scaibunker:admin, scaibunker:admin:tenant, scaibunker:admin:platform). See ScaiBunker → Permissions for the full table.

Implicit grants on tenant / partner admin roles. Tenant admins and partner admins receive every module permission by default through a short-circuit in has_module_permission. This means a tenant_admin automatically has scaibunker:admin:tenant (the intent), and also nominally has scaibunker:admin:platform (which is route-gated separately to platform-only operations like cross-tenant availability-group management). Module routes that need platform-scope authorization check the user's role rather than the module-permission flag.

See each module's page in the Modules section for its full permission list.

How permissions resolve#

A user's effective permissions come from three sources, combined:

1. Role-based permissions. Each role the user has contributes its permission set. A tenant_user contributes models:use, api_keys:manage, etc. A user can have multiple roles (unusual but supported) and their effective permissions are the union.
2. Group mappings. ScaiKey groups can map to ScaiGrid roles via the role_mappings table. If you're in a ScaiKey group mapped to tenant_admin, you get that role whenever you authenticate. Configure via /v1/role-mappings.
3. Module permissions. Users can have per-module permissions granted directly (not through a role). These are additive — a user who's a tenant_user plus has scaibot:manage granted can use models and manage bots, but not other admin functions. Configure via /v1/users/{user_id}/module-permissions.

Effective permission set = (role permissions) ∪ (group-mapped permissions) ∪ (direct module permissions).

Per-resource ACLs (some modules)#

Some modules layer a per-resource ACL on top of the role/permission system. The role/permission system gates whether you can use the module's API; the ACL gates which specific resources within the module you can touch.

ScaiMatrix is the most prominent example — collections and individual documents each carry an NTFS-style ACL with allow/deny entries, parent inheritance, and an owner concept. A user with scaimatrix:search can call the search endpoint, but the ACL decides which collections and documents the search results actually contain.

When both a module permission and an ACL apply, the user needs both. Group memberships are expanded transitively where the module supports it, including nested groups.

Custom roles#

If the six built-in roles don't match your access pattern, create a custom role. Custom roles are tenant-scoped, composed from any mix of core permissions and module permissions.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

curl -X POST https://scaigrid.scailabs.ai/v1/custom-roles \
  -H "Authorization: Bearer $TENANT_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics Team",
    "slug": "analytics",
    "description": "Can view all tenant usage and export reports, no admin access",
    "core_permissions": ["accounting:view_tenant", "models:list"],
    "module_permissions": []
  }'

Assign to a user:

1
2
3

curl -X PUT https://scaigrid.scailabs.ai/v1/users/{user_id}/roles \
  -H "Authorization: Bearer $TENANT_ADMIN_TOKEN" \
  -d '{"roles": ["tenant_user"], "custom_role_ids": ["role_abc"]}'

Custom roles can include any module permission the tenant has enabled. See Custom Roles.

Checking permissions programmatically#

The current user's permissions are available at /v1/me:

1

curl -H "Authorization: Bearer $TOKEN" https://scaigrid.scailabs.ai/v1/me

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "status": "ok",
  "data": {
    "user_id": "...",
    "email": "alice@acme.example",
    "tenant_id": "...",
    "roles": ["tenant_admin"],
    "permissions": ["models:use", "users:manage", ...],
    "module_permissions": ["scaibot:manage", "scaimatrix:search", ...]
  }
}

Useful for building permission-aware UI — show the "Manage users" button only to callers with users:manage.

What happens on a permission denial#

Requests without sufficient permissions return 403 AUTHZ_PERMISSION_DENIED:

1
2
3
4
5
6
7

{
  "status": "error",
  "error": {
    "code": "AUTHZ_PERMISSION_DENIED",
    "message": "User lacks required permission"
  }
}

No indication of which specific permission is missing — to avoid leaking the permission taxonomy to unauthenticated callers. Authenticated admins can inspect a user's permissions directly.

What's next#

• Custom Roles — design patterns for tenant-specific access control.
• Authentication — how tokens and API keys are issued.
• Users and Access Reference — full endpoint list.