Roles & multi-tenancy (RBAC)

Pylon’s RBAC layer keeps roles in AuthContext.roles and the active tenant in AuthContext.tenant_id. Policies reference them through auth.hasRole(...) and auth.tenantId. More complex authorization stays in policy expressions or server functions. This page covers the data model, the policy syntax, and the patterns for typical multi-tenant apps.

Roles

AuthContext.roles is a string array. Organization roles must be built-ins or declared in the app manifest:

buildManifest({
  // ...
  auth: { orgRoles: ["reviewer", "billing"] },
});

Roles are typically stored on a per-user, per-tenant join table:

{
  "name": "OrgMember",
  "fields": [
    { "name": "userId", "type": "id(User)",  "optional": false },
    { "name": "orgId",  "type": "id(Org)",   "optional": false },
    { "name": "role",   "type": "string",    "optional": false }
  ],
  "indexes": [
    { "name": "by_user_org", "fields": ["userId", "orgId"], "unique": true }
  ]
}

When the user calls /api/auth/select-org, the runtime loads the matching OrgMember.role into the session so policy auth.hasRole(...) / auth.hasAnyRole(...) checks see them on every request. (There is no auth.roles array binding in the policy DSL. Roles are reachable only through those two functions.)

Special roles

Name	What it does
`admin` admin context	Bypasses writes. Bypasses reads only with no active org (see the note). `auth.hasRole('x')` returns true for any `x`.

Organization owners and admins receive only their exact org role in roles. The framework org-management routes authorize those built-ins separately. Custom roles have no inheritance: a reviewer does not satisfy member or admin. An admin context with an active org is a special case. Its writes still bypass every policy. Its reads do not. Pylon scopes an admin read to the active org, and the read policy runs. So the admin sees only that org’s rows, like a member. An admin context with no active org (an operator, PYLON_ADMIN_TOKEN, or Studio) bypasses reads too.

Policy syntax

Policies live in pylon.manifest.json under policies:

{
  "policies": [
    {
      "match": "Todo",
      "read":  "auth.userId != null",
      "write": "auth.userId == data.authorId || auth.hasRole('admin')",
      "delete":"auth.hasRole('admin')"
    }
  ]
}

match is the entity name. The other fields are boolean expressions over auth and data:

Identifier	Type	Meaning
`auth.userId`	string \| null	Current user id, null if anonymous
`auth.isAdmin`	bool	True for admin contexts
`auth.tenantId`	string \| null	Active org id
`auth.hasRole('x')`	fn → bool	Role check (admin returns true for any role)
`auth.hasAnyRole('a','b')`	fn → bool	Match any of the roles
`data.<field>`	varies	Row column value

Supported operators: ==, !=, <, <=, >, >=, &&, ||, !, parentheses, plus numeric literals and the now binding. Ordering compares numbers numerically and ISO-8601 strings chronologically (deny-safe otherwise). There is no arithmetic and no in/ends_with/starts_with. Role checks use the auth.hasRole(...) / auth.hasAnyRole(...) functions; cross-entity membership uses exists(Entity where field == <expr> [and ...]). String matching belongs in a function.

Common patterns

Row-scoped to author

Only the author can read or write their row:

{
  "match": "Note",
  "read":  "data.authorId == auth.userId",
  "write": "data.authorId == auth.userId"
}

Row-scoped to tenant

Multi-tenant apps where rows belong to an org and members of that org can access them:

{
  "match": "Project",
  "read":  "data.orgId == auth.tenantId",
  "write": "data.orgId == auth.tenantId && auth.hasAnyRole('editor', 'admin')"
}

The tenant_id flows in through the session. See Sessions → Multi-tenant.

Role-gated mutation

Read is open to all members; write requires elevation:

{
  "match": "OrgSettings",
  "read":  "data.orgId == auth.tenantId",
  "write": "data.orgId == auth.tenantId && auth.hasRole('owner')"
}

Public read, owner write

Common for blog posts / public profiles:

{
  "match": "Post",
  "read":  "true",
  "write": "data.authorId == auth.userId"
}

Soft “no one but admin”

Most internal/system tables:

{
  "match": "AuditLog",
  "read":  "auth.hasRole('admin')",
  "write": "auth.hasRole('admin')",
  "delete":"false"
}

"delete": "false" blocks delete entirely. Admins can read and write but never remove.

Where policies run

Policies enforce on every entity-level operation: CRUD via /api/entities/*, sync push, and query reads. They do not run inside server functions. Once you are in a mutation or action handler, you have direct DB access via ctx.db. Use functions when a policy is too complex to express as an expression.

// Function-level enforcement (when policies aren't enough)
import { mutation } from "@pylonsync/functions";

export default mutation({
  args: { todoId: v.string() },
  async handler(ctx, args) {
    const todo = await ctx.db.get("Todo", args.todoId);
    if (!todo) throw new Error("not found");

    // Custom policy: only authors can mark done after a deadline
    const isAuthor = todo.authorId === ctx.auth.userId;
    const isPastDeadline = Date.now() > new Date(todo.deadline).getTime();
    if (isPastDeadline && !isAuthor) throw new Error("only the author can edit overdue todos");

    await ctx.db.update("Todo", args.todoId, { done: true });
  },
});

Reading roles in functions

Inside a mutation / query / action, ctx.auth exposes:

ctx.auth.userId        // string | null
ctx.auth.isAdmin       // boolean
ctx.auth.tenantId      // string | null
ctx.auth.roles         // string[] — exact active-org/session role slugs
ctx.auth.elevate({ admin: true, reason: "..." })  // promote after verifying a webhook/HMAC

The handler ctx.auth carries no hasRole helper and no email. roles is useful for branching and rendering, but authorization should use the ctx.requireMember helper. It looks up the membership row and fails closed:

// throws UNAUTHENTICATED / FORBIDDEN if the caller isn't an owner of this org
const member = await ctx.requireMember(args.orgId, { role: "owner" });

Functions bypass policies, so a mutation or action with a forgotten membership check is an IDOR. The manifest declares which role strings are valid. Assignments live on the membership table, which is what requireMember reads.

Granting roles

Role assignments are strings on the membership table. Prefer the built-in PUT /api/auth/orgs/:orgId/members/:userId endpoint, which validates them against built-ins plus auth.orgRoles. A custom mutation should apply the same allowlist:

import { mutation, v } from "@pylonsync/functions";

const VALID_ROLES = new Set(["owner", "admin", "member", "reviewer"]);

export default mutation({
  args: { targetUserId: v.string(), role: v.string() },
  async handler(ctx, args) {
    if (!ctx.auth.tenantId) throw new Error("must select an org first");
    if (!VALID_ROLES.has(args.role)) {
      throw ctx.error("INVALID_ARGS", "role is not declared by this app");
    }
    // Gate authorization on the current membership row.
    // requireMember reads OrgMember and throws FORBIDDEN if the caller isn't an owner.
    await ctx.requireMember(ctx.auth.tenantId, { role: "owner" });

    const existing = await ctx.db.query("OrgMember", {
      where: { userId: args.targetUserId, orgId: ctx.auth.tenantId },
    });
    if (existing.length === 0) throw new Error("not a member of this org");

    await ctx.db.update("OrgMember", existing[0].id, { role: args.role });
  },
});

Extending beyond roles

For finer-grained access, build a permission table and check it in policies with exists(Permission where todoId == existing.id and userId == auth.userId). Keep complex rules in a server function when they no longer read clearly as policy expressions.

Admin token

PYLON_ADMIN_TOKEN is set in the environment. A request that passes it as Authorization: Bearer <token> resolves to AuthContext::admin(): isAdmin: true, and every hasRole(...) returns true. This context has no active org, so it bypasses every policy, including reads. This is for:

Migrations / backfills (pylon migrate apply)
Studio (the inspector)
CLI commands (pylon export, pylon backup)
Server-to-server calls between trusted services

Treat the admin token like a root password. Rotate it quarterly. See Token rotation.

Testing policies

Pylon runs policies in the same evaluator your tests can use:

import { evalPolicy } from "@pylonsync/sdk/test";

const allowed = evalPolicy(
  "auth.userId == data.authorId",
  { auth: { userId: "u1", isAdmin: false, roles: [] }, data: { authorId: "u1" } }
);
// → true

Or assert via the HTTP layer in integration tests:

test("non-author can't edit", async () => {
  const session = await signInAs("u2");
  const res = await fetch(`/api/entities/Todo/${todoId}`, {
    method: "PATCH",
    headers: { Authorization: `Bearer ${session.token}` },
    body: JSON.stringify({ title: "hacked" }),
  });
  expect(res.status).toBe(403);
});

Recipes

Personal apps — single-user, no roles, no policies. Just auth.userId != null.
SaaS — tenant_id everywhere, roles on OrgMember, policies match data.orgId == auth.tenantId.
Forum / community — auth.hasRole('moderator') for soft-delete and ban actions.
Marketplaces — separate Buyer and Seller roles, policies check both.
Internal tools — single admin role, broad gates, audit log via the audit_log plugin.

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Migrate

Roles & multi-tenancy (RBAC)

Roles

Special roles

Policy syntax

Common patterns

Row-scoped to author

Row-scoped to tenant

Role-gated mutation

Public read, owner write

Soft “no one but admin”

Where policies run

Reading roles in functions

Granting roles

Extending beyond roles

Admin token

Testing policies

Recipes

​Roles

​Special roles

​Policy syntax

​Common patterns

​Row-scoped to author

​Row-scoped to tenant

​Role-gated mutation

​Public read, owner write

​Soft “no one but admin”

​Where policies run

​Reading roles in functions

​Granting roles

​Extending beyond roles

​Admin token

​Testing policies

​Recipes

Roles

Special roles

Policy syntax

Common patterns

Row-scoped to author

Row-scoped to tenant

Role-gated mutation

Public read, owner write

Soft “no one but admin”

Where policies run

Reading roles in functions

Granting roles

Extending beyond roles

Admin token

Testing policies

Recipes