Skip to main content
apps/web uses workspace-scoped permissions, not a single coarse role string, to decide what a signed-in user can see or mutate. The important implementation detail is that modern permission checks do not read workspace_members.role. The effective permission set is computed from:
  • workspace_role_members
  • workspace_role_permissions
  • workspace_default_permissions
  • workspace creator fallback logic in getPermissions()
workspace_default_permissions is typed by member_type:
  • MEMBER rows are the normal workspace defaults for members and API keys.
  • GUEST rows are signed-in guest defaults. Missing guest rows mean denied.
Guest defaults use the same workspace_role_permission catalog as member defaults, including management and admin bits, but guests are still denied on dashboard routes that have no mapped permission. For the full workspace model, including URL resolution and API-key auth, see platform/architecture/workspaces-permissions.

​
Core Helper

The main entry point is getPermissions() in packages/utils/src/workspace-helper.ts. It evaluates permissions in this order:
  1. Authenticate the current user with a request-scoped or cookie-scoped Supabase client.
  2. Normalize the incoming workspace identifier so personal and internal become real workspace IDs.
  3. Verify caller membership with verifyWorkspaceMembershipType(..., requiredType: 'ANY') so the helper can distinguish MEMBER from GUEST.
  4. For MEMBER, load role-derived permissions from workspace_role_members -> workspace_roles -> workspace_role_permissions.
  5. Load workspace-wide defaults from workspace_default_permissions using the resolved member_type.
  6. Load the workspace creator and treat that member as an implicit superuser.
If the user is the workspace creator, getPermissions() returns the full permission catalog from packages/utils/src/permissions.tsx. If the user is not the creator, getPermissions() returns the deduplicated union of:
  • enabled permissions from every assigned workspace role
  • enabled default workspace permissions for the resolved membership type
If the user has no effective permissions and is not the creator, the helper returns null. For GUEST, role-derived permissions and creator fallback are skipped. The helper only reads workspace_default_permissions.member_type = 'GUEST', so a guest with no enabled guest defaults receives no effective permissions.

​
admin Is A Permission Bit

admin is part of the normal permission catalog. It is not a separate evaluator or a special membership table. Once containsPermission() sees admin in the effective permission list, it treats every permission check as allowed: 
const isAdmin = permissions.includes('admin');

const containsPermission = (permission: PermissionId) => {
  return isCreator || isAdmin || permissions.includes(permission);
};
That means creator and admin behave similarly at call sites, even though they come from different sources:
  • creator access is implicit and computed in code
  • admin access is explicit and stored like any other permission
For guests, admin can satisfy a mapped permission route, but it does not open routes with no permission mapping. The dashboard shell stays default-deny for guest routes that cannot be tied to a permission ID.

​
Permission Catalog

The permission catalog lives in packages/utils/src/permissions.tsx. The non-root workspace groups currently include permissions for:
  • workspace administration
  • AI
  • calendar
  • projects
  • documents
  • time tracking
  • drive
  • users
  • user groups
  • leads
  • inventory
  • finance
  • workforce
  • transactions
  • invoices
The root workspace adds an extra infrastructure-only group. Some catalog entries are also conditionally exposed for root or @tuturuuu.com users. This matters because creator fallback uses the catalog directly. If a permission is added to the product but not added to the catalog, creator fallback and roles UI drift immediately.

​
Where Web Pages Use It

Typical server-page flow in apps/web:
  1. Resolve the workspace with WorkspaceWrapper or getWorkspace().
  2. Call getPermissions({ wsId }).
  3. Redirect or notFound() when the required permission is missing.
  4. Pass containsPermission / withoutPermission into the page composition.
Examples:
  • apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/roles/page.tsx
  • apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/members/page.tsx
  • apps/web/src/app/[locale]/(dashboard)/[wsId]/(workspace-settings)/settings/page.tsx
  • apps/web/src/app/[locale]/(dashboard)/[wsId]/navigation.tsx
navigation.tsx is especially important because a large part of the UX is permission-driven before the user even clicks into a page. Sidebar items are disabled or hidden from withoutPermission(...), and some cross-workspace admin affordances also compare root-workspace permissions.

​
Where API Routes Use It

There are three common patterns in apps/web routes.

​
1. Session auth only

Some routes only verify that the caller is signed in, usually through createClient(request) or withSessionAuth(...). Use this when the operation is about the current signed-in user or the route does not grant privileged workspace mutations by itself.

​
2. Membership + workspace normalization

Many workspace-scoped routes first convert the route param into a canonical workspace ID with normalizeWorkspaceId(wsId, supabase) and then verify membership. This is the baseline for routes that accept personal or internal in the URL but must query by UUID in the database. For non-permission routes that still require protected workspace access, use verifyWorkspaceMembershipType(...) from packages/utils/src/workspace-helper.ts and keep the default requiredType (MEMBER). 
const membership = await verifyWorkspaceMembershipType({
  wsId: normalizedWsId,
  userId: user.id,
  supabase,
});

if (membership.error === 'membership_lookup_failed') {
  return NextResponse.json({ message: 'Failed to verify workspace access' }, { status: 500 });
}

if (!membership.ok) {
  return NextResponse.json({ message: "You don't have access to this workspace" }, { status: 403 });
}
workspace_members now supports MEMBER and GUEST. If a route is not explicitly guest-capable, it should require MEMBER and avoid ad-hoc .from('workspace_members') checks that only validate row existence. normalizeWorkspaceId('personal', ...) also enforces MEMBER membership on the personal-workspace join path by filtering workspace_members.type = 'MEMBER'. Course consumption routes are the exception that combine both models: MEMBER workspace rows keep normal course access, while GUEST rows must pass workspace_guest_permissions resource checks such as course:view.

​
3. Membership + explicit permission gate

Privileged routes call getPermissions() after normalization and reject when containsPermission(...) fails. This is the pattern to use for settings, finance, roles, infrastructure, and any other restricted mutation surface. If a route writes workspace membership, invitations, roles, or other authorization data with createAdminClient() / service-role privileges, enforce the relevant permission before the admin write. A workspace_members row alone is never enough for those flows: invite creation and membership-type changes require manage_workspace_members, and workspace_members.type is protected at the database layer so non-managers cannot self-promote from GUEST to MEMBER. When a server page or API route uses createAdminClient() after a workspace permission gate, the protected row lookup must still prove the row belongs to the authorized route scope. For nested resources, include every trusted parent identifier in the same query or RPC: 
await admin
  .schema('private')
  .from('user_group_posts')
  .select('id, group_id, workspace_user_groups!inner(ws_id)')
  .eq('id', postId)
  .eq('group_id', groupId)
  .eq('workspace_user_groups.ws_id', normalizedWsId)
  .maybeSingle();
Do not load a child row by ID with service-role privileges and then separately validate only the supplied parent route data. A mismatched child ID can expose cross-workspace data before later related lookups return empty results. Education authoring and review APIs are also feature-gated. Routes that expose quiz answer keys, learner attempt metadata, flashcards, quiz sets, or other Education admin surfaces must use apps/web/src/lib/education/access.ts so ENABLE_EDUCATION and ai_lab are enforced server-side before any workspace-scoped read or mutation. Mobile and other clients may hide Education affordances, but API routes remain the source of truth for this gate.

​
API Keys Reuse The Same Permission IDs

External SDK routes use withApiAuth(...) in apps/web/src/lib/api-middleware.ts. The API key evaluator:
  • authenticates a workspace API key from workspace_api_keys
  • binds the request to exactly one workspace
  • computes the effective permissions as role permissions ∪ MEMBER default permissions
  • rejects requests whose [wsId] route param does not match the API key’s workspace
That keeps permission IDs consistent across browser/session routes and external API routes, even though the authentication mechanism is different.

​
Current Design Rules

  • Use getPermissions() for feature-level authorization in server pages and session-auth routes.
  • Use normalizeWorkspaceId() before querying workspace-scoped tables from route params.
  • Do not assume workspace_members.role represents the effective permission model in apps/web.
  • Treat admin as a permission that short-circuits checks, not as a separate role system.
  • When adding new privileged features, update both the permission catalog and the UI/routes that consume it.