# Managing Roles and Permissions in the UI

> Create and assign roles, permissions, and permission groups using Supamode's visual interface. No SQL required.

*Canonical: https://makerkit.dev/docs/supamode/configuration/permissions*

---

Supamode provides a visual interface for managing your entire permission structure. This guide covers creating roles, permissions, and permission groups through the UI.

**Prerequisites:** You must be signed in with a role that has system permissions for `role`, `permission`, and `account` resources (typically Super Admin or Root).

## Managing Roles

Roles define what users can do in Supamode. Every admin account has exactly one role, and that role determines their permissions.

### Viewing Roles

Navigate to **Settings > Permissions** and select the **Roles** tab (`/settings/permissions?tab=roles`).

{% img src="/images/supamode/roles.webp" alt="Roles list showing all defined roles with their ranks" width="1724" height="292" /%}

Click any role to view its details, including assigned permissions and permission groups.

{% img src="/images/supamode/role-details.webp" alt="Role details showing permissions and groups" width="1724" height="292" /%}

### Creating a Role

1. Click **New Role** in the top right
2. Fill in the role details:
   - **Name**: A descriptive name (e.g., "Content Editor", "Support Agent")
   - **Description**: What this role is for
   - **Rank**: The role's position in the hierarchy (0-100)

{% img src="/images/supamode/create-role-dialog.webp" alt="Create role dialog with name, description, and rank fields" width="1724" height="292" /%}

### Understanding Role Rank

Rank determines who can manage whom:
- Higher rank users can manage lower rank users
- A rank 70 user cannot modify a rank 80 account
- Use this to prevent junior admins from elevating privileges

**Recommended rank structure:**
- Root/Super Admin: 100
- Admin: 90
- Developer: 80
- Manager: 70
- Support: 60
- Viewer: 50

## Creating Permissions

Navigate to **Settings > Permissions** and select the **Permissions** tab (`/settings/permissions?tab=permissions`).

Click **New Permission** to create a new permission.

{% img src="/images/supamode/create-permission-dialog.webp" alt="Permission creation dialog" width="1724" height="292" /%}

### Permission Fields

| Field | Description |
|-------|-------------|
| **Name** | Descriptive name (e.g., "Edit Blog Posts") |
| **Description** | What this permission allows |
| **Type** | System (admin features) or Data (database access) |
| **Scope** | For data permissions: Table or Storage |
| **Action** | What operations are allowed |

### System Permissions

System permissions control access to Supamode's admin features. Use these for managing users, roles, and system settings.

**System resources:**
- `account` - Manage Supamode accounts
- `role` - Create and edit roles
- `permission` - Manage permissions
- `auth_user` - Manage Supabase Auth users
- `table` - Configure table metadata
- `log` - Access audit logs
- `system_setting` - Modify system settings

### Data Permissions

Data permissions control access to your database tables and storage buckets.

#### Table Permissions

Configure access to specific tables:

{% img src="/images/supamode/data-permission-form.webp" alt="Data permission form with schema and table fields" width="1724" height="292" /%}

| Field | Description | Example |
|-------|-------------|---------|
| **Schema** | Database schema | `public`, `billing`, `*` |
| **Table** | Table name | `posts`, `users`, `*` |
| **Action** | Operation type | `select`, `insert`, `update`, `delete`, `*` |

Use `*` as a wildcard:
- `public.*` grants access to all tables in public schema
- `*.*` grants access to all tables (use sparingly)

#### Storage Permissions

Configure access to Supabase Storage buckets:

{% img src="/images/supamode/storage-permission-form.webp" alt="Storage permission form with bucket and path fields" width="1724" height="292" /%}

| Field | Description | Example |
|-------|-------------|---------|
| **Bucket** | Storage bucket name | `avatars`, `documents`, `*` |
| **Path Pattern** | File path pattern | `users/*`, `public/*`, `*` |
| **Action** | Operation type | `select`, `insert`, `update`, `delete`, `*` |

Path patterns work like SQL `LIKE`:
- `users/*` matches all files in the users folder
- `*` matches all files in the bucket

## Assigning Permissions to Roles

You can assign permissions to roles in two ways:

1. **Direct assignment** - Add individual permissions to a role
2. **Permission groups** - Create reusable bundles of permissions

### Direct Assignment

1. Navigate to a role's detail page
2. Click **Manage Permissions**
3. Select the permissions to assign

{% img src="/images/supamode/manage-permissions.webp" alt="Manage permissions dialog showing available permissions" width="1724" height="292" /%}

### Using Permission Groups

Permission groups bundle related permissions together. Assign a group to multiple roles, and updating the group updates all roles using it.

#### Creating a Permission Group

1. Go to **Settings > Permissions > Permission Groups** tab
2. Click **New Permission Group**
3. Add a name and description

{% img src="/images/supamode/permission-groups.webp" alt="Permission groups list" width="1724" height="292" /%}

#### Adding Permissions to a Group

1. Click on a permission group to view details
2. Click **Manage Permissions**
3. Select permissions to include

{% img src="/images/supamode/permission-group-details.webp" alt="Permission group details with assigned permissions" width="1724" height="292" /%}

{% img src="/images/supamode/manage-group-permissions.webp" alt="Adding permissions to a group" width="1724" height="292" /%}

#### Assigning Groups to Roles

1. Navigate to a role's detail page
2. Click **Manage Permission Groups**
3. Select groups to assign

{% img src="/images/supamode/manage-permissions-group.webp" alt="Assigning permission groups to a role" width="1724" height="292" /%}

## Example: Setting Up a Content Editor Role

Here's a practical example of creating a role for content editors:

1. **Create the role:**
   - Name: "Content Editor"
   - Description: "Can manage blog posts and media"
   - Rank: 60
2. **Create permissions:**
   - "Read All Posts" (Data, Table: `public.posts`, Action: select)
   - "Edit Posts" (Data, Table: `public.posts`, Action: update)
   - "Create Posts" (Data, Table: `public.posts`, Action: insert)
   - "Manage Media" (Data, Storage: `media`, Path: `*`, Action: `*`)
3. **Create a permission group:**
   - Name: "Content Management"
   - Add all four permissions above
4. **Assign to role:**
   - Open the Content Editor role
   - Click Manage Permission Groups
   - Add the Content Management group

Now any user assigned the Content Editor role can manage posts and media, but cannot access other tables or admin features.

{% faq
   title="Frequently Asked Questions"
   items=[
     {"question": "Should I use direct permissions or permission groups?", "answer": "Permission groups are recommended for most cases. They make it easier to manage permissions across multiple roles and keep your permission structure organized. Use direct assignment only for one-off permissions specific to a single role."},
     {"question": "Can I use wildcards safely?", "answer": "Use wildcards carefully. Schema-level wildcards (public.*) are reasonable for admin roles. Database-level wildcards (*.*) should only be used for Super Admin/Root roles. Always prefer specific table permissions when possible."},
     {"question": "How do I see which roles have a specific permission?", "answer": "Open the permission's detail page. It shows all roles that have this permission, either directly or through permission groups."},
     {"question": "What happens if I delete a permission that's assigned to roles?", "answer": "The permission is removed from all roles and permission groups that had it. Users with those roles lose that specific access immediately."},
     {"question": "Can I duplicate a role?", "answer": "There's no direct duplicate feature, but you can create a new role and assign the same permission groups. This is why permission groups are useful - you can reuse them across multiple roles."}
   ]
/%}