Group permissions
Build a workspace with roles, using a members table and existence-based permissions.This recipe shows how to build a workspace where users have different levels of access depending on their role. The same pattern applies to any group-like concept — teams, projects, channels, organisations.
Roles at a glance
| Role | Read | Create | Edit own | Edit any | Manage members |
|---|---|---|---|---|---|
reader | ✓ | ||||
contributor | ✓ | ✓ | ✓ | ||
writer | ✓ | ✓ | ✓ | ✓ | |
admin | ✓ | ✓ | ✓ | ✓ | ✓ |
Schema
Three tables: the workspace itself, a members join table that records each user's role, and the documents that belong to the workspace.
schema.tsimport { schema as s } from "jazz-tools";export const schema = s.defineSchema({documents: s.table({ title: s.string(), content: s.string(), workspaceId: s.uuid() },{workspace: s.rel("workspaces", "workspaceId"),},),workspaceMembers: s.table({workspaceId: s.uuid(),user_id: s.uuid(),role: s.enum("reader", "writer", "contributor", "admin"),},{workspace: s.rel("workspaces", "workspaceId"),},),workspaces: s.table({ name: s.string() },{documents: s.reverse("documents", "workspace"),members: s.reverse("workspaceMembers", "workspace"),},),});
Permissions
schema.tsconst { definePermissions, exists, session, anyOf, allOf } = schema;const isMember = (workspaceId: s.Uuid) =>exists.workspaceMembers({ workspaceId, user_id: session.user });const hasRole = (workspaceId: s.Uuid, role: "reader" | "writer" | "contributor" | "admin") =>exists.workspaceMembers({ workspaceId, user_id: session.user, role });const isAdmin = (workspaceId: s.Uuid) => hasRole(workspaceId, "admin");const createdByMe = { $createdBy: session.user };const mine = { user_id: session.user };export const permissions = definePermissions({documents: {read: (document) => isMember(document.workspaceId),insert: (document) =>anyOf(hasRole(document.workspaceId, "writer"),hasRole(document.workspaceId, "contributor"),isAdmin(document.workspaceId),),update: (document) =>anyOf(hasRole(document.workspaceId, "writer"),isAdmin(document.workspaceId),allOf(createdByMe, hasRole(document.workspaceId, "contributor")),),delete: (document) =>anyOf(hasRole(document.workspaceId, "writer"),isAdmin(document.workspaceId),allOf(createdByMe, hasRole(document.workspaceId, "contributor")),),},workspaceMembers: {read: (workspaceMember) => isMember(workspaceMember.workspaceId),insert: (workspaceMember) =>anyOf(isAdmin(workspaceMember.workspaceId),allOf({ user_id: session.user, role: "admin" },workspaceMember.workspace.where(createdByMe),),),update: (workspaceMember) => isAdmin(workspaceMember.workspaceId),delete: (workspaceMember) => anyOf(isAdmin(workspaceMember.workspaceId), mine),},workspaces: {read: (workspace) => isMember(workspace.id),insert: true,update: (workspace) => isAdmin(workspace.id),delete: (workspace) => isAdmin(workspace.id),},});
isMember, hasRole and isAdmin are plain TypeScript helpers: they take the workspace id to check
(document.workspaceId on a document, workspaceMember.workspaceId on a membership, workspace.id
on a workspace). createdByMe and mine are plain conditions. npx jazz-tools generate inlines
them all into jazz.permissions.json.
- Contributor edit and delete access requires both
createdByMe({ $createdBy: session.user }: the row belongs to this author) and a matching contributor membership. Writers and admins can edit and delete any document. - Bootstrap insert: the second branch of the
workspaceMembersinsert policy lets the workspace creator add themselves as the first admin (workspaceMember.workspace.where(createdByMe)checks the workspace the new row points to) — otherwiseisAdminwould block everyone, since there are no members yet. - Leave on your own: members can delete their own membership row (
mine) regardless of role. Admins can remove anyone.
See Declarative Permissions for more on exists, anyOf, allOf, relation .where, and $createdBy.
Creating a workspace
export async function createWorkspace(db: ReturnType<typeof useDb>,name: string,creatorId: string,) {const { value: workspace } = await db.insert(app.workspaces, { name });// Add the creator as admin immediately so they can manage the workspacedb.insert(app.workspaceMembers, {workspaceId: workspace.id,user_id: creatorId,role: "admin",});return workspace;}
Managing members
Adding a member
export async function addMember(db: ReturnType<typeof useDb>,workspaceId: string,userId: string,role: "reader" | "writer" | "contributor" | "admin",) {await db.insert(app.workspaceMembers, { workspaceId, user_id: userId, role });}
Listing members
WorkspaceMembers.tsxexport function WorkspaceMembers({ workspaceId }: { workspaceId: string }) {const { data: members = [], isLoading } = useAll(app.workspaceMembers.where({ workspaceId }));if (isLoading) return <p>Loading…</p>;return (<ul>{members.map((member) => (<li key={member.id}>{member.user_id} — {member.role}</li>))}</ul>);}
Changing a member's role
export async function changeRole(db: ReturnType<typeof useDb>,memberId: string,newRole: "reader" | "contributor" | "writer" | "admin",) {await db.update(app.workspaceMembers, memberId, { role: newRole });}
Removing a member
export async function removeMember(db: ReturnType<typeof useDb>,workspaceId: string,userId: string,) {const member = await db.one(app.workspaceMembers.where({ workspaceId, user_id: userId }));if (member) await db.delete(app.workspaceMembers, member.id);}
What a removed member still sees
- Online (thin client, or local-first while connected): the workspace's documents drop out of their live queries right away.
- Offline local-first: the rows already on their device stay readable, across reloads too, until they reconnect. Within about a second of reconnecting they are removed from the device. Writes they queued meanwhile are rejected and reverted.
clearOnSignOutdoesn't help here: a removed member isn't signed out.
Anything they read before removal they may have copied; removing access stops future reads, not past ones.
Querying documents
WorkspaceDocuments.tsxexport function WorkspaceDocuments({ workspaceId }: { workspaceId: string }) {const { data: docs, isLoading, error } = useAll(app.documents.where({ workspaceId }));if (isLoading) return <p>Loading…</p>;if (error) return <p>Something went wrong!</p>;return (<ul>{docs.map((doc) => (<li key={doc.id}>{doc.title}</li>))}</ul>);}