Skip to main content

​
scopes.json schema

{
  "scopes": [
    { "name": "tasks:viewAll", "description": "View all users' tasks" }
  ],
  "tables": {
    "Task": {
      "ownerColumn": "userId",
      "bypassScopes": { "read": "tasks:viewAll", "write": "tasks:editAll" }
    }
  },
  "services": {
    "workflows": {
      "requiredScopes": [],
      "tools": {
        "scheduleDraft": ["workflows:schedules:editOwn"],
        "scheduleJob": ["workflows:schedules:editOwn"]
      }
    }
  }
}

​
Scope naming conventions

PatternExampleUse case
resource:actiontasks:viewAllApp-level permissions
service:resource:actiongithub:repos:writeService-level permissions
Common actions: view, viewAll, edit, editAll, create, delete, manage

​
Enforcement layers

LayerMechanismConfiguration
FrontendProtectedRoute with requiredScopesApp.tsx route definitions
BackendscopedProcedure(['scope'])Procedure definitions
DatabaseRLS policiestables section of scopes.json
AI agentProcedure access based on user’s scopes; direct service access gated by services section of scopes.jsonAutomatic from procedure scopes + services config

​
Frontend routes

// Authentication required
<ProtectedRoute>
  <MyPage />
</ProtectedRoute>

// Scope-based (user must have at least one of the listed scopes)
<ProtectedRoute requiredScopes={["users:viewAll", "roles:view"]}>
  <AdminPage />
</ProtectedRoute>
Frontend route protection is a UX convenience — the actual security enforcement happens on the backend via scopedProcedure and database-level RLS.

​
Procedure enforcement

// Any authenticated user
getMyTasks: scopedProcedure([])

// Requires tasks:viewAll scope
getAllTasks: scopedProcedure(['tasks:viewAll'])

// Requires all listed scopes (AND)
adminReport: scopedProcedure(['tasks:viewAll', 'reports:view'])

// Requires any one of the listed scopes (OR)
viewReport: scopedProcedure(['tasks:viewAll', 'reports:view'], 'any')
Create separate procedures for different access levels rather than checking scopes inside a handler. The build validator blocks ctx.userScopes access and getUserScopes imports in procedure handlers — use scopedProcedure for all scope enforcement.

​
Service access control

The services section controls which service tools the AI agent can access per user. Each service entry has requiredScopes (scopes needed to use any tool from that service) and tools (per-tool scope overrides): 
{
  "services": {
    "workflows": {
      "requiredScopes": [],
      "tools": {
        "scheduleDraft": ["workflows:schedules:editOwn"],
        "scheduleJob": ["workflows:schedules:editOwn"],
        "updateSchedule": ["workflows:schedules:editOwn"],
        "deleteSchedule": ["workflows:schedules:editOwn"]
      }
    }
  }
}
  • requiredScopes: [] — any authenticated user can use the service’s tools (unless overridden per-tool)
  • tools — maps tool names to arrays of required scopes for that specific tool

​
System scopes

The framework defines system scopes for built-in features. These are included in the scaffolded scopes.json and assigned to the Admin role:
ScopeDescription
scopes:viewView all scopes
scopes:configureConfigure scope org-assignability
roles:viewView all roles and their scopes
roles:editCreate, update, and delete roles
users:viewAllView all users
users:editAllEdit all users
users:viewRolesView role assignments for all users
users:editRolesAssign and remove roles from users
orgs:viewAllView all organizations
orgs:editCreate, update, and delete organizations
orgs:manageMembersAdd and remove members from any organization
orgs:manageOrgMembersManage members and roles in your own organization
app:settingsManage app access settings
services:manageManage service configurations and credentials
oauth:appsCreate and manage your own OAuth applications
oauth:adminAdminister all OAuth clients and identity providers
logs:viewView application logs
workflows:jobs:viewAllView all users’ workflow jobs
workflows:jobs:editAllEdit and cancel any user’s workflow jobs
workflows:schedules:viewAllView all users’ workflow schedules
workflows:schedules:editOwnCreate, edit, and delete own workflow schedules
workflows:schedules:editAllEdit and delete any user’s workflow schedules
workflows:drafts:viewAllView all users’ workflow drafts
workflows:drafts:editAllEdit and delete any user’s workflow drafts
System scopes have "isSystem": true and "orgAssignable": false in the scope definition.

​
Default roles

Roles are not defined in scopes.json. Default roles (Admin, Member) are seeded at first build via seed:publisher. The database is the source of truth for roles — users with roles:edit scope can create and edit roles at runtime.
RoleScopesManaged
AdminAll defined scopes + system scopesSystem role (cannot be deleted)
MemberNone (base authenticated access)Default for new users

​
Build-time validation

  • Every scope in tables and services must exist in the scopes array
  • Every table and column in tables must exist in the Prisma schema
  • Every service in services must have its client package installed
  • Forbidden patterns (ctx.userScopes, _unscopedPrisma, $executeRaw) are blocked