RBAC & Permissions

The workspace authorisation model: roles are assigned via Clerk metadata, permissions are strings, and a role unlocks a fixed set of permissions defined in lib/auth/rbac-shared.ts.

This page should be auto-generated from lib/auth/rbac-shared.ts so it never drifts. See /operations/observability for the planned docs-gen script. The matrix below is hand-maintained until that lands.

Roles (13)#

Permission categories#

Permissions follow the pattern org:<feature>:<action>. Categories:

• org:sys:* — system administration (domains, SSO, audit logs).
• org:team:* — team management.
• org:billing:* — billing & invoices.
• org:content:* — content studio (create / edit / publish / delete / archive / view / SEO).
• org:leads:* — lead management (view / export / sync).
• org:analytics:* — analytics dashboards & exports.
• org:dev:* — developer tools (API keys, webhooks, internal tools).
• org:hrm:* — HR module (jobs, candidates).
• org:legal:* — legal policies & audit (policies_edit / policies_publish / audit_view).
• org:webinars:* — webinar CRUD, partners, registrations.
• org:glossary:* — glossary CRUD + analytics.
• org:observability:* — unified System Health module (11 permissions): view, services_view, integrations_view, integrations_run, diagnostics_view, logs_view, errors_view, webhooks_view, analytics_view, pii_view, manage.

How a permission check works#

// API route handler
import { checkRole } from "@/lib/auth/rbac";

export async function POST(req: NextRequest) {
  if (!(await checkRole("org:content:create"))) {
    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
  }
  // …mutation logic
}

checkRole reads the caller's roles from Clerk session claims (with an API fallback) and returns true iff at least one of those roles grants the requested permission.

For Server Components, use the redirecting guard from lib/auth/guards.ts. On failure it calls Next's redirect() (default target /workspace) rather than throwing:

import { requirePermission } from "@/lib/auth/guards";

export default async function AdminPage() {
  await requirePermission("org:sys:manage");   // redirect("/workspace") on failure
  return <Dashboard />;
}

// Override the redirect target with the optional second arg:
// await requirePermission("org:sys:manage", "/some/other/path");

Adding a permission#

1. Add the string to the Permission type in lib/auth/rbac-shared.ts.
2. Add it to the role(s) that should have it inside ROLE_PERMISSIONS.
3. Call checkRole("org:new:permission") from the relevant route handler.
4. Update this docs page (or wait for the docs-gen script).

Adding a role#

1. Add to the Role union in lib/auth/rbac-shared.ts.
2. Add an entry to ROLE_PERMISSIONS, ROLE_LABELS, ROLE_HIERARCHY.
3. If the role is privileged (super-admin level), add it to PROTECTED_ROLES.
4. Assign the role via Clerk dashboard → user → publicMetadata.role (the primary role string) plus publicMetadata.additionalRoles (an array of any extra role strings). There is no publicMetadata.roles field.