> ## Documentation Index
> Fetch the complete documentation index at: https://synthetiq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Access control reference

> scopes.json schema, scope naming, enforcement layers, and service access control

## scopes.json schema

```json theme={null}
{
  "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

```typescript theme={null}
// 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

```typescript theme={null}
// 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):

```json theme={null}
{
  "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