Authorization

Overview

Authorization in the Refresh platform determines what a user can do after authentication proves who they are. The system follows the principle of least privilege: users receive only the minimum permissions required for their role, with granular resource:action permissions checked at every API endpoint.

Key Principle: FusionAuth proves "this is Taylor" → Your database answers "what can Taylor do?"

Evolution of the Auth System

The authorization system has evolved through three major iterations, each addressing limitations discovered in the previous approach.

Phase 1: Auth.js with Database Roles (Initial)

The original system used Auth.js (formerly NextAuth) for authentication with role columns directly on membership tables:

┌─────────────────────────────────────────────────────────────────┐
│  PHASE 1: Auth.js + Database Role Columns                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Authentication: Auth.js (Google, Microsoft OAuth)               │
│  Session: Drizzle adapter storing sessions in Postgres           │
│                                                                  │
│  Role Storage:                                                   │
│  • tenant_users.role → 'owner' | 'admin' | 'member'             │
│  • group_users.role  → 'admin' | 'member'                       │
│  • users.role        → 'user' | 'admin' (platform level)        │
│                                                                  │
│  Permission Checking:                                            │
│  • Hardcoded role checks: if (role === 'admin') { ... }         │
│  • No granular permissions                                       │
│  • Role implies all capabilities for that level                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Limitations:

• No granular permissions - "admin" meant everything or nothing

• Hardcoded role checks scattered throughout codebase

• No support for M2M/service authentication

• No way to create custom roles per tenant

• Difficult to audit what each role could actually do

Phase 2: FusionAuth with Permissions Table

Migrated to FusionAuth for authentication and introduced a permissions table mapping roles to granular permissions:

┌─────────────────────────────────────────────────────────────────┐
│  PHASE 2: FusionAuth + Permissions Table                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Authentication: FusionAuth (OAuth, SSO, self-registration)      │
│  Identity: FusionAuth Groups → Roles in JWT                      │
│                                                                  │
│  Role Storage (Hybrid):                                          │
│  • JWT roles claim    → Internal team roles (refresh.*)          │
│  • tenant_users.role  → Tenant membership roles                  │
│  • group_users.role   → Group membership roles                   │
│                                                                  │
│  Permission Resolution:                                          │
│  • permissions table: (role, permission, bypass_rls)             │
│  • Roles from JWT + database resolved to permissions             │
│  • RLS used get_permission() function                            │
│                                                                  │
│  Schema:                                                         │
│  CREATE TABLE permissions (                                      │
│    role TEXT,           -- 'tenant.admin', 'refresh.developer'   │
│    permission TEXT,     -- 'surveys:create', 'users:delete'      │
│    bypass_rls BOOLEAN   -- Allow cross-tenant access             │
│  );                                                              │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Improvements over Phase 1:

• Granular resource:action permissions

• FusionAuth handled identity, MFA, SSO

• M2M support via FusionAuth Entities

• bypass_rls flag for internal team cross-tenant access

• Centralized permission definitions

Remaining Limitations:

• Roles still hardcoded in tenant_users.role and group_users.role columns

• No custom roles - tenants stuck with predefined owner/admin/member

• Permission changes required code deployment (new rows in permissions table)

• No admin UI for managing permissions or roles

• JWT roles for internal team, database roles for customers - inconsistent

• OAuth scopes not properly integrated with permission system

Phase 3: Fully Database-Managed Authorization (Current)

Complete redesign with all authorization managed in database tables, enabling runtime customization:

┌─────────────────────────────────────────────────────────────────┐
│  PHASE 3: Database-Managed Authorization (Current)               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Authentication: FusionAuth (unchanged)                          │
│  Identity: FusionAuth sub claim → user_auth_identities           │
│                                                                  │
│  Authorization (ALL in database):                                │
│  • auth_permission     → Atomic permission definitions           │
│  • auth_role           → Role definitions with scope_type        │
│  • auth_role_permission→ Role to permission mapping              │
│  • auth_assignment     → User to role in specific scope          │
│  • auth_permission_cache → Denormalized for RLS performance      │
│                                                                  │
│  OAuth/M2M:                                                      │
│  • oauth_scope         → Versioned scope definitions             │
│  • oauth_scope_permission → Scope to permission mapping          │
│  • api_client_scope    → Client to scope assignment              │
│                                                                  │
│  Key Features:                                                   │
│  • Custom roles per tenant                                       │
│  • Admin UI for all auth management                              │
│  • is_tenant_assignable controls permission visibility           │
│  • is_internal hides platform scopes from tenant admins          │
│  • Automatic cache invalidation via triggers                     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Improvements over Phase 2:

• Custom roles: Tenants can create their own roles with custom permission sets

• Admin UI: Full management interface for permissions, roles, scopes, clients

• Consistent model: All users (internal and external) use same auth tables

• Runtime changes: No code deployment needed for permission/role changes

• OAuth scopes: Proper scope→permission mapping for M2M clients

• Visibility controls: is_tenant_assignable and is_internal flags

• Performance: Denormalized cache with automatic invalidation

Migration Summary

Aspect	Phase 1	Phase 2	Phase 3 (Current)
Auth Provider	Auth.js	FusionAuth	FusionAuth
Role Storage	Column on each table	JWT + columns	auth_assignment table
Permissions	Hardcoded checks	permissions table	auth_permission + junction
Custom Roles	No	No	Yes
Admin UI	No	No	Yes
M2M Support	No	Basic (Entities)	Full (OAuth scopes)
RLS Function	Direct role checks	get_permission()	has_permission()

Deprecated Elements

The following were removed in Phase 3:

• tenant_users.role column → replaced by auth_assignment

• group_users.role column → replaced by auth_assignment

• permissions table → replaced by auth_permission + auth_role_permission

• get_permission() function → replaced by has_permission()

• is_tenant_admin() / is_group_admin() functions → replaced by permission checks

• JWT roles for permission resolution → all from database now

Lessons Learned

1. Don't embed roles in membership tables - Use a separate assignment table for flexibility

2. Separate permissions from roles - Allows role customization without changing permissions

3. Plan for multi-tenancy from the start - Custom roles per tenant is a common requirement

4. Build admin UI early - Manual database edits don't scale

5. Cache strategically - RLS performance matters; use denormalized cache with triggers

6. OAuth scopes ≠ permissions - Scopes are coarse-grained bundles for API clients

Defense-in-Depth Architecture

Authorization is enforced at multiple layers, with the API layer serving as the primary guard and database RLS as a backup safety net:

┌─────────────────────────────────────────────────────────────────────────────┐
│                           AUTHORIZATION LAYERS                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  LAYER 1: API MIDDLEWARE / JWT AUTHORIZER ← PRIMARY ENFORCEMENT             │
│  ─────────────────────────────────────────────────────────────              │
│  • Validate JWT signature via JWKS                                          │
│  • Resolve principal (user or API client) from JWT sub claim                │
│  • Query auth_permission_cache for all permissions                          │
│  • Reject unauthorized requests BEFORE any database query                   │
│                                                                              │
│  LAYER 2: DATABASE RLS (Postgres) ← BACKUP SAFETY NET                       │
│  ─────────────────────────────────────────────────────                      │
│  • Same checks via has_permission() function                                │
│  • Catches any bugs or missing middleware in new endpoints                  │
│  • Alerts if API allowed but RLS blocked (indicates bug)                    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Why Defense-in-Depth?

• If a new endpoint is added without proper middleware, RLS still blocks unauthorized access

• If RLS is misconfigured on a new table, API middleware still enforces access control

• Both layers use the same permission logic via has_permission(), providing consistent enforcement

Authorization Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                         AUTHENTICATION LAYER                                 │
│                         (FusionAuth - "Who are you?")                        │
├─────────────────────────────────────────────────────────────────────────────┤
│  User Login → JWT with `sub` (FusionAuth User ID)                           │
│  M2M Token → JWT with `sub` (FusionAuth Entity ID)                          │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         IDENTITY RESOLUTION                                  │
│                         (Database - "Map to internal ID")                   │
├─────────────────────────────────────────────────────────────────────────────┤
│  User: user_auth_identities.fusionauth_id → user_id                         │
│  M2M:  api_clients.fusionauth_entity_id → api_client_id + bound tenant      │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    AUTHORIZATION RESOLUTION                                  │
│                    (Database - "What can you access?")                      │
├─────────────────────────────────────────────────────────────────────────────┤
│  Fetch ALL access from auth_permission_cache:                               │
│  • Global permissions (personal account + internal users)                   │
│  • All tenant access + permissions per tenant                               │
│  • All group access + permissions per group (for API use)                   │
│  • bypass_rls flag (computed from roles)                                    │
│                                                                              │
│  Return complete AuthContext - no headers needed                            │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         API ENDPOINTS                                        │
│                         (Use AuthContext from path params)                  │
├─────────────────────────────────────────────────────────────────────────────┤
│  GET /v1/tenants/:tenantId/groups/:groupId                                  │
│  → Look up ctx.tenants[tenantId] or ctx.groups[groupId]                     │
│  → Check permission exists (API enforces all levels)                        │
│  → Execute (RLS enforces tenant/user level as backup)                       │
└─────────────────────────────────────────────────────────────────────────────┘

Security Model: RLS vs API Enforcement

Two Layers of Defense

Layer	Enforces	Purpose
API	Global, Tenant, Group, User	Primary enforcement - full business logic
RLS	Global, Tenant, User	Backup safety net - prevents data leakage if API has bugs

Why RLS Doesn't Enforce Groups

1. Groups are organizational, not security boundaries - They're for internal structure (teams, departments), not isolating sensitive data between untrusted parties.

2. All users in a tenant work for the same company - A team lead seeing another team's compliance data is an internal policy issue, not a data breach.

3. Simpler = more secure in practice - Fewer moving parts means fewer bugs.

Security Boundaries

┌─────────────────────────────────────────────────────────────────┐
│                     SECURITY BOUNDARIES                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────┐    ┌─────────────┐                             │
│  │  TENANT A   │    │  TENANT B   │   ← RLS ENFORCED            │
│  │             │    │             │     (hard boundary)          │
│  │  ┌───┐ ┌───┐│    │  ┌───┐ ┌───┐│                             │
│  │  │Grp│ │Grp││    │  │Grp│ │Grp││   ← API ENFORCED            │
│  │  │ 1 │ │ 2 ││    │  │ 3 │ │ 4 ││     (soft boundary)         │
│  │  └───┘ └───┘│    │  └───┘ └───┘│                             │
│  └─────────────┘    └─────────────┘                             │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │  USER PERSONAL DATA (files, profile)  ← RLS ENFORCED        ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

Role Classification System

Roles are classified based on two key fields: tenant_id and bypass_rls. This determines who can see the role and where it can be assigned.

tenant_id	bypass_rls	Category	Who Sees It	Who Can Use It	Example
NULL	true	Platform	Platform admins only	Internal team only	Super Admin, Developer
NULL	false	System	All tenants	Any tenant admin	Account Owner, Employee
{refresh_tenant}	true	Internal	Refresh tenant only	Internal team (with bypass)	Sales, Customer Success
{tenant_uuid}	false	Custom	That tenant only	That tenant's admin	Acme's "Regional Manager"

Role Scope Types

Each role has a scope_type that determines where it can be assigned:

scope_type	Description	Assignment
global	Platform-wide access	No scope_id needed
tenant	Tenant-scoped access	Requires tenant_id as scope_id
group	Group-scoped access	Requires group_id as scope_id

bypass_rls Behavior

Important: bypass_rls means "skip tenant isolation for permissions you have" - NOT "superuser access to everything".

A user with bypass_rls and tenant:list can list ALL tenants, but cannot access permission:create if they don't have that permission.

Database Constraint

-- Only system roles (tenant_id = NULL) can have bypass_rls
ALTER TABLE auth_role ADD CONSTRAINT bypass_rls_system_only
  CHECK (bypass_rls = false OR tenant_id IS NULL);

Platform Roles (Internal Team)

These roles are for Refresh OS internal staff only. They have bypass_rls = true which allows access across all tenants.

Super Admin

• Scope: global

• bypass_rls: true

• Description: Full platform access with all permissions

Platform Admin

• Scope: global

• bypass_rls: true

• Description: Broad read access for business visibility, limited write access

Developer

• Scope: global

• bypass_rls: true

• Description: Development-focused access for debugging and maintenance

Support

• Scope: global

• bypass_rls: true

• Description: Read-only access for troubleshooting customer issues

System Roles (Tenant Scope)

These roles are available to all tenants as default options. They have tenant_id = NULL and bypass_rls = false.

Account Owner

• Scope: tenant

• Description: Highest authority within a tenant. Full control including billing.

Organization Admin

• Scope: tenant

• Description: Full administrative access without billing control.

Compliance Manager

• Scope: tenant

• Description: Focused on compliance and audit functionality.

HR Administrator

• Scope: tenant

• Description: Manages employee data and HR functions.

Manager

• Scope: tenant

• Description: Limited to managing direct reports.

Employee

• Scope: tenant

• Description: Basic access for regular employees.

Permission System

Permission Naming Convention

Permissions follow the pattern [category.]resource:action:

[category.]resource:action

Examples:
  tenant:list, tenant:get, tenant:create, tenant:update, tenant:delete
  compliance.control:list, compliance.framework:publish
  integrations:sync:preview, integrations:sync:apply
  auth.permission:create, auth.role:update

• Category (optional): Groups related permissions (e.g., auth., compliance.)

• Resource: The entity being accessed (e.g., tenant, user, role)

• Action: The operation being performed (e.g., list, get, create, update, delete)

Standard Actions

Action	Description
list	Query/list multiple records
get	Get single record by ID
create	Create a new record
update	Modify an existing record
delete	Archive/soft delete a record
publish	Publish draft (versioned tables)

Permission Visibility

The is_tenant_assignable flag on auth_permission controls which permissions tenant admins can assign to custom roles:

is_tenant_assignable	Available To	Examples
true (default)	All roles (system + custom)	user:list, compliance.control:update
false	Platform/Internal roles only	auth.permission:create, auth.oauth-scope:update

Permissions that should have is_tenant_assignable = false:

• All auth.* permissions (auth system management)

• All auth.oauth-scope* permissions (OAuth scope management)

• redaction:* permissions (internal data operations)

Database Schema

Core Auth Tables

auth_permission - Atomic Capabilities

CREATE TABLE auth_permission (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(100) NOT NULL UNIQUE,         -- 'compliance.control:list'
  description TEXT,
  resource VARCHAR(50) NOT NULL,             -- 'compliance.control'
  action VARCHAR(50) NOT NULL,               -- 'list'
  category VARCHAR(50),                      -- 'Compliance'
  is_tenant_assignable BOOLEAN NOT NULL DEFAULT true,
  created_date TIMESTAMPTZ NOT NULL DEFAULT now()
);

auth_role - Permission Groups

CREATE TABLE auth_role (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(100) NOT NULL,
  description TEXT,
  scope_type VARCHAR(20) NOT NULL CHECK (scope_type IN ('global', 'tenant', 'group')),
  tenant_id UUID REFERENCES tenants(id),
  bypass_rls BOOLEAN NOT NULL DEFAULT false,
  created_date TIMESTAMPTZ NOT NULL DEFAULT now(),
  archived_date TIMESTAMPTZ,
  UNIQUE(name, tenant_id)
);

auth_role_permission - Role → Permission Mapping

CREATE TABLE auth_role_permission (
  role_id UUID NOT NULL REFERENCES auth_role(id) ON DELETE CASCADE,
  permission_id UUID NOT NULL REFERENCES auth_permission(id) ON DELETE CASCADE,
  PRIMARY KEY (role_id, permission_id)
);

auth_assignment - User → Role in Scope

CREATE TABLE auth_assignment (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id),
  role_id UUID NOT NULL REFERENCES auth_role(id),
  scope_type VARCHAR(20) NOT NULL CHECK (scope_type IN ('global', 'tenant', 'group')),
  scope_id UUID,  -- NULL for global, tenant_id or group_id otherwise
  created_date TIMESTAMPTZ NOT NULL DEFAULT now(),
  archived_date TIMESTAMPTZ,
  UNIQUE(user_id, role_id, scope_type, COALESCE(scope_id, '00000000-0000-0000-0000-000000000000'))
);

auth_permission_cache - Denormalized for RLS Performance

CREATE TABLE auth_permission_cache (
  principal_type VARCHAR(20) NOT NULL,  -- 'user' | 'api_client'
  principal_id UUID NOT NULL,
  permission_name VARCHAR(100) NOT NULL,
  scope_type VARCHAR(20) NOT NULL,      -- 'global' | 'tenant'
  scope_id UUID,
  bypass_rls BOOLEAN NOT NULL DEFAULT false,
  cached_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  expires_at TIMESTAMPTZ NOT NULL DEFAULT (now() + INTERVAL '60 minutes'),
  PRIMARY KEY (principal_type, principal_id, permission_name, scope_type, COALESCE(scope_id, '00000000-0000-0000-0000-000000000000'))
);

RLS Permission Function

The has_permission() function is used by all RLS policies:

CREATE TYPE permission_result AS (
  is_authorized BOOLEAN,
  bypass_rls BOOLEAN
);

CREATE OR REPLACE FUNCTION has_permission(
  p_session JSONB,
  p_permissions TEXT[],  -- Array of permission names (OR logic)
  p_tenant_id UUID DEFAULT NULL
) RETURNS permission_result AS $$
-- Implementation queries auth_permission_cache
-- Returns is_authorized=true if user has ANY of the required permissions
-- Returns bypass_rls=true if any matching permission has bypass_rls=true
$$ LANGUAGE plpgsql STABLE SECURITY DEFINER;

RLS Policy Examples

// Tenant-scoped table
pgPolicy('select-policy', {
	for: 'select',
	using: sql`(has_permission(auth.session(), ARRAY['compliance.control:list'], ${t.tenantId})).is_authorized`
});

// User-owned table with bypass check
pgPolicy('select-policy', {
	for: 'select',
	using: sql`
    (has_permission(auth.session(), ARRAY['file:list'])).is_authorized
    AND (
      (has_permission(auth.session(), ARRAY['file:list'])).bypass_rls
      OR ${t.ownerId} = auth_user(auth.user_id())
    )
  `
});

OAuth Scopes (M2M Authentication)

OAuth scopes bundle permissions for M2M API clients. Scopes use a resource:action naming pattern separate from the permission system.

Scope vs Permission

Concept	Granularity	Example	Used By
Permission	Fine-grained	user:get, user:list, user:create	Users via roles
OAuth Scope	Coarse-grained	employees:read, employees:write	API clients

A single OAuth scope maps to multiple permissions:

• employees:read → user:get, user:list

• employees:write → user:create, user:update

OAuth Scope Tables

oauth_scope - Versioned Scopes

CREATE TABLE oauth_scope (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  entity_id UUID NOT NULL,                   -- Stable ID across all versions
  version INT NOT NULL DEFAULT 1,
  name VARCHAR(100) NOT NULL,                -- Auto-generated: '{resource}:{action}'
  description TEXT,
  resource VARCHAR(50) NOT NULL,             -- 'employees', 'surveys'
  action VARCHAR(50) NOT NULL,               -- 'read', 'write', 'manage'
  category VARCHAR(50),                      -- For UI organization
  is_internal BOOLEAN NOT NULL DEFAULT false, -- Hide from tenant admins
  status VARCHAR(20) NOT NULL DEFAULT 'draft',
  created_date TIMESTAMPTZ NOT NULL DEFAULT now(),
  archived_date TIMESTAMPTZ,
  UNIQUE(entity_id, version)
);

oauth_scope_permission - Scope → Permission Mapping

CREATE TABLE oauth_scope_permission (
  scope_id UUID NOT NULL REFERENCES oauth_scope(id) ON DELETE CASCADE,
  permission_id UUID NOT NULL REFERENCES auth_permission(id) ON DELETE CASCADE,
  PRIMARY KEY (scope_id, permission_id)
);

Internal vs External Scopes

is_internal	Visible To	Use Case
false	All admins	External API scopes (employees:read, surveys:write)
true	Platform admins only	Internal service scopes (platform:admin)

The is_internal flag ensures tenant admins cannot see or assign platform-level scopes that grant cross-tenant access.

Scope Naming Convention

Scopes use simplified resource:action patterns:

• employees:read - Read employee data

• employees:write - Create/update employees

• surveys:manage - Full survey access

• platform:admin - Internal platform access (is_internal = true)

M2M Client Types

Type	bypass_rls	tenant_id	Access
Internal system (api-core)	true	NULL	All tenants
External tenant-bound	false	<tenant-uuid>	Only that tenant
External unbound	false	NULL	No tenant access (personal/global only)

M2M Token Flow

┌─────────────────────────────────────────────────────────────────┐
│                    External M2M Token Flow                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  M2M Token:                                                      │
│  {                                                               │
│    "sub": "<entity-id>",        ← The M2M app                    │
│    "scope": "employees:read",   ← What it can do                 │
│    "aud": "<api-app-id>"        ← No user context                │
│  }                                                               │
│                   │                                              │
│                   ▼                                              │
│  API validates:                                                  │
│  1. Token valid? ✓                                               │
│  2. Has required scope? ✓                                        │
│  3. Look up: SELECT tenant_id FROM api_clients                   │
│              WHERE fusionauth_entity_id = ?                      │
│  4. Resolve scope → permissions via oauth_scope_permission       │
│  5. Does requested tenant match bound tenant?                    │
│     └── NO → 403 Forbidden                                       │
│     └── YES → Return data                                        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

AuthContext Structure

The JWT authorizer resolves ALL access upfront and returns an AuthContext:

interface AuthContext {
	principalType: 'user' | 'api_client';
	principalId: string;
	bypassRls: boolean;

	global: {
		permissions: string[];
	};

	tenants: Record<
		string,
		{
			permissions: string[];
		}
	>;

	groups: Record<
		string,
		{
			tenantId: string;
			permissions: string[];
		}
	>;
}

Frontend Permission Structure

The frontend receives permissions via locals.permissions:

interface ResolvedPermission {
	permission: string; // 'compliance.control:list'
	bypassRls: boolean; // true if came from bypass_rls role
}

// Usage in Svelte
const canCreate = $derived(
	locals.permissions?.some((p) => p.permission === 'compliance.control:create')
);

UI Permission Guards

PermissionGuard Component

Use PermissionGuard to conditionally render UI based on permissions:

<script>
	import { PermissionGuard } from '$lib/components/permission-guards';
</script>

<!-- Check for permission -->
<PermissionGuard permissions={['surveys:create']}>
	<button onclick={createSurvey}>New Survey</button>
</PermissionGuard>

<!-- With fallback for unauthorized -->
<PermissionGuard permissions={['integrations:list']} fallbackType="unauthorized">
	<IntegrationsPage />
</PermissionGuard>

usePermissions Hook

For programmatic permission checks:

<script>
	import { usePermissions } from '$lib/hooks/use-permissions.svelte';

	const { hasPermission } = usePermissions();

	const canCreate = $derived(hasPermission('surveys:create'));

	// Check with bypassRls requirement
	const canManageAllTenants = $derived(hasPermission('tenant:list', { requireBypassRls: true }));
</script>

Important: UI gating is for UX only. Always enforce permissions server-side via RLS and API checks.

Cache Invalidation

Triggers automatically invalidate auth_permission_cache when:

• auth_assignment changes (user role assignment)

• auth_role changes (role archived, bypass_rls changed)

• auth_role_permission changes (permission added/removed from role)

• auth_permission changes (permission renamed/deleted)

• api_client_scope changes (M2M client scopes)

• oauth_scope_permission changes (scope permissions)

Custom Roles

Tenants can create custom roles for their specific needs:

• tenant_id: Set to the creating tenant's ID

• bypass_rls: Always false (enforced by database constraint)

• scope_type: Can be tenant or group

• Permissions: Limited to is_tenant_assignable = true permissions

Example Custom Roles

• "Regional Manager" - Access to specific groups only

• "Compliance Reviewer" - Read-only compliance without employee data

• "HR Assistant" - Limited HR functions

Best Practices

1. Always check server-side - UI gating is for UX only; never trust client-side permission checks

2. Use specific permissions - Prefer document:create over broad patterns

3. Fail closed - Deny by default if permission isn't explicitly granted

4. Least privilege - Assign minimum permissions needed for each role

5. Audit role changes - Track who assigned which roles and when

Related Documentation

• Authentication Flow - JWT and FusionAuth setup

• User Management - User identity lifecycle

• Multi-Tenancy - Tenant isolation

• Developer Authentication Guide - Implementation details

---

Last updated: December 2025