Role And Permission Matrix

This page documents the real access model behind the product.

If you want to understand why the UI behaves differently across account, organization, and admin pages, start here.

The Three Contexts

The same user can move through all three contexts, but authorization rules are not the same across them.

Active Organization

The active tenant is stored in session state as activeOrganizationId.

That value matters because:

• organization layouts require it
• organization procedures depend on it
• the SSE notification stream depends on it
• the tRPC client scopes cache keys by organization to avoid cross-tenant data leakage

Organization switching is done by writing the new active organization into Better Auth session state, then navigating into /dashboard/organization.

sign in
  -> choose organization from /dashboard
  -> set activeOrganizationId in session
  -> clear org-scoped client cache
  -> enter /dashboard/organization

Platform Roles

Current platform roles:

• user
• admin

admin is the only platform role that can access /dashboard/admin/* and protectedAdminProcedure.

Organization Roles

Current organization roles:

• owner
• admin
• member

These roles are resolved from organization membership after the active organization is validated.

Procedure Types

This means tenant access control is enforced server-side, not only in navigation.

Real Permission Boundaries

Platform Admin

Can access:

• admin user management
• admin organization management
• admin notification publishing
• platform alerts and exports

Important limitation:

• platform admin does not automatically bypass organization membership checks used by protectedOrganizationProcedure
• organization-scoped mutations still depend on membership and, for many high-trust actions, organization role

Organization Owner And Admin

Can manage higher-trust organization workflows such as:

• API keys
• webhook configuration and test delivery
• billing and subscriptions
• credits and auto top-up controls
• managed deployment actions in Contract Lab, Indexer Lab, and Channel Lab

Organization Member

Still has organization-scoped access through protectedOrganizationProcedure, including common workspace workflows such as:

• viewing and working inside the organization workspace
• lead CRUD and lead exports
• notifications and shared operational context
• creating and reading organization AI chats when access rules allow it

But members are not allowed to manage:

• API keys
• webhooks
• billing
• deployment control actions gated to owners/admins

Important Nuance: Chat Ownership

Organization AI chat has an extra ownership layer:

• shared chats can be read by other eligible members
• only the chat owner can edit, delete, pin, or change sharing settings

So not every organization-scoped workflow is purely role-based. Some are user-owned within the tenant.

Tenant Isolation Guarantees

The codebase enforces tenant separation through:

• active organization checks
• membership validation before returning organization data
• organizationId filters in database access
• organization-scoped query cache keys on the client

That combination is what makes the tenant model credible.

Route Protection Model

public route
  -> no session required

protected route / procedure
  -> valid session required

organization route / procedure
  -> valid session
  -> activeOrganizationId present
  -> user must be a member of that organization

admin route / procedure
  -> valid session
  -> user.role must be admin

Practical Matrix

Related Pages

• Reference Overview
• Security and Governance
• Route Map
• Architecture and Operating Model