In this comprehensive guide, we'll explore Supamode's straightforward yet powerful role-based access control (RBAC) system, designed to give you granular control over who can access what in your Supabase application.

Key Learning Objectives:

• Master the four core components of Supamode's permission architecture
• Implement secure, multi-layered access verification
• Design scalable permission structures for your organization
• Deploy production-ready access control using seed templates

The Four Core Components of Supamode 🏗️

Supamode's access control system is built around four interconnected components that work together to create secure, manageable permissions.

1. Accounts: User accounts linked with Supabase's auth users
2. Roles: Roles that define authority levels. You can assign one role to each account.
3. Permissions: Fine-grained access rights that control what actions users can perform. There are two types of permissions: system permissions and data permissions.
   • System Permissions: Control access to Supamode's administrative interface and system functions.
   • Data Permissions: Control access to your actual application data with incredible granularity.
4. Permission Groups: Optional logical bundles of related permissions for easier role management. A role can have multiple permission groups assigned to it.

Example:

1. Account: A user has an account in Supamode, which is linked to their Supabase auth user.
2. Role: The user is assigned a role, such as "Content Editor", which defines their authority level. All roles have a priority, which determines their authority level.
3. Permissions: The "Content Editor" role has permissions like "Create Blog Posts" and "Edit Own Blog Posts", which define what actions the user can perform.
4. Permission Groups: The "Content Editor" role is part of a "Content Management" permission group, which bundles related permissions together for easier management.

1. Accounts: Your Identity Foundation 👤

What it is: The bridge between Supabase's authentication system and Supamode's permission management.

// Account Structure
{
  id: "uuid-account-id",
  auth_user_id: "uuid-from-supabase-auth", // Links to auth.users
  is_active: true
}

Key Concept: Every authenticated user gets exactly one Supamode account. The account is necessary for being assigned roles and permissions, and it allows you to store additional metadata about the user.

Accounts with status is_active: false are considered deactivated and cannot perform any actions in Supamode. This is useful for managing user access without deleting accounts.

2. Roles: Authority Levels 👑

Roles define the authority levels within your application, allowing you to control what users can do based on their assigned role.

A user can have a single role, which is assigned to their account. Roles are defined by their name, description, priority, and optional metadata.

// Role Structure
{
  name: "Content Manager",
  description: "Manages blog posts and user content",
  priority: 70, // Higher = more authority
  metadata: {
    department: "Marketing"
  }
}

Visual Hierarchy:

Super Admin (Priority: 100)    ← Ultimate system control
├── Admin (Priority: 90)       ← System administration
├── Manager (Priority: 70)     ← Content management
├── Editor (Priority: 60)      ← Content editing
└── Viewer (Priority: 50)      ← Read-only access

Key Concept: Roles have priorities that determine authority levels, but do not inherit permissions. Each role must be explicitly assigned its own permissions.

A role with a higher priority can perform actions on roles that have lower priority, such as assigning them a different role, editing their account, and so on. However, they also must have the required permissions to modify accounts.

Supamode does not define any roles by default, allowing you to create a custom hierarchy that fits your application's needs.

3. Permissions: Granular Access Rights 🎯

What it is: The atomic units of access control that define specific actions on specific resources.

Supamode uses two distinct permission types:

• System Permissions: Control access to Supamode's administrative interface and system functions.
• Data Permissions: Control access to your actual application data with incredible granularity.

System Permissions: Administrative Control

Control access to Supamode's administrative interface and system functions.

// System Permission Example
{
  permission_type: "system",
  name: "Manage User Accounts",
  system_resource: "account",    // What system resource
  action: "update",              // What action is allowed
  description: "Can modify user account details"
}

Available System Resources:

• account - Managing user accounts in Supamode
• role - Creating and editing roles
• permission - Managing permission definitions
• auth_user - Managing auth accounts in Supabase (e.g., creating users, banning accounts, etc.)
• table - Database table configuration
• log - System audit log access

Normally, you would grant this sort of permissions to high-level roles like Admin or Super Admin, who need to manage the entire system.

Data Permissions: Application Content Control

Control access to your actual application data with incredible granularity.

// Table-Level Data Permission
{
  permission_type: "data",
  name: "Edit Blog Posts",
  scope: "table",
  schema_name: "public",
  table_name: "blog_posts",
  action: "update"
}
// Schema-Wide Data Permission
{
  permission_type: "data",
  name: "Read All Public Data",
  scope: "table",
  schema_name: "public",
  table_name: "*",              // Wildcard for all tables
  action: "select"
}

Granularity Levels:

Schema Level:   public.* (entire schema)
├── Table Level:  public.blog_posts (specific table)
└── Column Level: public.users.email (specific column)

This is the permission type you'll use most often, which grants read/write access to specific tables or columns.

For example, you might have permissions like:

• "Read All Blog Posts" - View all blog content for Content Management role
• "Create Blog Posts" - Allow content creators to add new posts
• "Manage all data" - Full access to all data in the application, typically reserved for Super Admins
• "Readonly" - Read-only access to all data in the application, typically reserved for Viewer role

4. Permission Groups: Logical Organization 📦

What it is: Bundles of related permissions that make role management intuitive and scalable. Permission groups are fully optional, but they can greatly simplify your permission management.

// Content Management Group
{
  name: "Content Management",
  description: "All permissions needed for content creators",
  permissions: [
    "Read All Blog Posts",
    "Create Blog Posts",
    "Edit Own Blog Posts",
    "Upload Media Files",
    "Moderate Comments"
  ]
}

Strategic Grouping Examples:

• "Content Management" → Blog editing, media upload, comment moderation
• "User Administration" → Account creation, role assignment, access reviews
• "Customer Support" → Ticket access, user lookup, limited account editing

Benefits:

• Simplified Role Creation - Assign entire groups instead of individual permissions
• Consistent Access Patterns - Related permissions stay together
• Easier Maintenance - Update group once, affects all roles using it

Why Use Permission Groups?

While users can only have a single role, a role can have multiple permission groups assigned to it. This allows you to create complex permission structures without overwhelming individual roles with too many permissions.

How Components Work Together 🔗

Here's how these components interact to create a complete access control system:

The Permission Assignment Flow

graph TB
    A[User Login] --> B[Account Lookup]
    B --> C[Role Assignment Check]
    C --> D[Permission Resolution]
    D --> E[Access Decision]
    subgraph "Permission Sources"
        F[Direct Role Permissions]
        G[Permission Group Permissions]
    end
    D --> F
    D --> G

Multi-Layer Security Verification: Defense in Depth 🛡️

Supamode implements three security layers to ensure comprehensive protection at every access point.

Understanding the Security Layers

Layer 1: JWT Token Validation (Lightning Fast) ⚡

Purpose: High-speed filtering of obviously invalid requests Performance: Microsecond response times, no database queries

select supamode.check_admin_access();

This functions checks the app_metadata field of the JWT token to ensure the user is an admin. We do so by checking if the app_metadata field contains the admin_access key set to true.

The is a preliminary, lightweight check that quickly filters out requests from users who are not admins.

This check is done both:

• On the API-side - The Hono API middleware runs this check before every request
• On the DB-side - The Supabase function supamode.check_admin_access() gets checked on every execution of a remote procedure call (RPC).

Layer 2: Database Permission Resolution (Comprehensive) 🗄️

Purpose: Deep, context-aware permission verification

-- Deep permission verification with complete context
SELECT supamode.has_permission(
  $current_user_account_id,
  $permission_id
) AS permission_granted;

The Resolution Process:

1. Account Lookup - Match JWT user to Supamode account
2. Role Collection - Gather all assigned roles
3. Permission Aggregation - Collect permissions from:

• Direct role assignments
• Permission group memberships

4. Override Application - Apply account-specific grants/denials
5. Final Decision - Boolean result with full audit trail

Layer 3: Multi-Factor Authentication (optional, but recommended) 🔐

Optionally, you can enforce MFA for all users, which is recommended for all applications.

If enabled, users must complete an additional authentication step before signing in and being able to access the Supamode interface/data.

Permission Resolution in Detail 🔍

Understanding how Supamode resolves permissions is crucial for designing effective access control.

The Permission Resolution Algorithm

flowchart TD
    A[User Makes Request] --> B[Check Account-Level Denials]
    B --> C{Explicit Denial?}
    C -->|Yes| D[Access Denied]
    C -->|No| E[Check Permission Sources]
    E --> F[Direct Account Permissions]
    E --> G[Role-Based Permissions]
    E --> H[Permission Group Permissions]
    F --> I{Any Grant Found?}
    G --> I
    H --> I
    I -->|Yes| J[Access Granted]
    I -->|No| K[Access Denied]

Permission Override System

Supamode supports account-specific permission overrides for exceptional cases:

-- Grant temporary admin access to a user
INSERT INTO supamode.account_permissions (
    account_id,
    permission_id,
    is_grant,
    valid_until,
    metadata
) VALUES (
    'user-account-id',
    (SELECT id FROM supamode.permissions WHERE name = 'Manage All Data'),
    true,
    '2025-12-31 23:59:59',
    '{"reason": "Temporary migration assistance"}'::jsonb
);

Override Use Cases:

• Temporary Access - Consultant needs admin access for 2 weeks
• Emergency Permissions - Support agent needs elevated access for critical issue
• Access Revocation - Suspend specific permissions for user under review

In the next steps, we will learn about:

1. Templates: Using the existing templates to deploy Supamode
2. Your own schema setup: Customizing the permission system to fit your needs
3. Mock Data: Adding mock data for development purposes