Access control reference

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

Pattern	Example	Use case
`resource:action`	`tasks:viewAll`	App-level permissions
`service:resource:action`	`github:repos:write`	Service-level permissions

Common actions: view, viewAll, edit, editAll, create, delete, manage

Enforcement layers

Layer	Mechanism	Configuration
Frontend	`ProtectedRoute` with `requiredScopes`	`App.tsx` route definitions
Backend	`scopedProcedure(['scope'])`	Procedure definitions
Database	RLS policies	`tables` section of `scopes.json`
AI agent	Procedure access based on user’s scopes; direct service access gated by `services` section of `scopes.json`	Automatic 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:

Scope	Description
`scopes:view`	View all scopes
`scopes:configure`	Configure scope org-assignability
`roles:view`	View all roles and their scopes
`roles:edit`	Create, update, and delete roles
`users:viewAll`	View all users
`users:editAll`	Edit all users
`users:viewRoles`	View role assignments for all users
`users:editRoles`	Assign and remove roles from users
`orgs:viewAll`	View all organizations
`orgs:edit`	Create, update, and delete organizations
`orgs:manageMembers`	Add and remove members from any organization
`orgs:manageOrgMembers`	Manage members and roles in your own organization
`app:settings`	Manage app access settings
`services:manage`	Manage service configurations and credentials
`oauth:apps`	Create and manage your own OAuth applications
`oauth:admin`	Administer all OAuth clients and identity providers
`logs:view`	View application logs
`workflows:jobs:viewAll`	View all users’ workflow jobs
`workflows:jobs:editAll`	Edit and cancel any user’s workflow jobs
`workflows:schedules:viewAll`	View all users’ workflow schedules
`workflows:schedules:editOwn`	Create, edit, and delete own workflow schedules
`workflows:schedules:editAll`	Edit and delete any user’s workflow schedules
`workflows:drafts:viewAll`	View all users’ workflow drafts
`workflows:drafts:editAll`	Edit 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.

Role	Scopes	Managed
Admin	All defined scopes + system scopes	System role (cannot be deleted)
Member	None (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

Platform Docs

Synthetiq Desktop

Synthetiq CLI

App Framework

Services Framework

Workflows Framework

Platform API

Deployments

Access control reference

scopes.json schema

Scope naming conventions

Enforcement layers

Frontend routes

Procedure enforcement

Service access control

System scopes

Default roles

Build-time validation

​scopes.json schema

​Scope naming conventions

​Enforcement layers

​Frontend routes

​Procedure enforcement

​Service access control

​System scopes

​Default roles

​Build-time validation

scopes.json schema

Scope naming conventions

Enforcement layers

Frontend routes

Procedure enforcement

Service access control

System scopes

Default roles

Build-time validation