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

RoleReadCreateEdit ownEdit anyManage 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.ts
import { 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.ts
const { 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 workspaceMembers insert policy lets the workspace creator add themselves as the first admin (workspaceMember.workspace.where(createdByMe) checks the workspace the new row points to) — otherwise isAdmin would 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 workspace
db.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.tsx
export 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.
  • clearOnSignOut doesn'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.tsx
export 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>
);
}