# Permission Templates

> Get started quickly with pre-built permission templates. Choose from solo, small team, SaaS, or custom configurations based on your team size and needs.

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

---

Supamode includes pre-defined seed templates that set up roles, permissions, and your initial admin account. Pick a template that matches your team structure and customize from there.

**Available templates:**
- **solo-seed.ts** - Single user with full access (solopreneurs)
- **small-team-seed.ts** - 3-10 people with role separation
- **saas-seed.ts** - Full RBAC structure for larger teams
- **custom-seed.ts** - Blank starting point for custom setups

## How Templates Work

Templates generate SQL that:
1. Creates roles with appropriate ranks
2. Defines permissions (system and data)
3. Bundles permissions into groups
4. Creates your initial admin account
5. Assigns the highest role to your account

After generating, you deploy the SQL as a Supabase migration.

## Choosing a Template

| Template | Best For | Roles Created | MFA Default |
|----------|----------|---------------|-------------|
| **solo** | Single developer | Solopreneur (rank 100) | Disabled |
| **small-team** | 3-10 people | Admin, Developer, Support | Disabled |
| **saas** | 10+ people, enterprise | Root, Admin, Manager, Developer, Support, Read Only | Disabled |
| **custom** | Unique requirements | None (you define) | You decide |

## Generating a Seed

Use the CLI to generate a seed file:

```bash
pnpm run generate-schema --template <template-name> --root-account <supabase-user-id>
```

**Parameters:**
- `--template`: Template name (`solo`, `small-team`, `saas`, or `custom`)
- `--root-account`: Your Supabase Auth user UUID

**Example:**
```bash
pnpm run generate-schema --template saas --root-account 550e8400-e29b-41d4-a716-446655440000
```

### Finding Your User ID

Get your Supabase Auth user ID from:
1. Supabase Dashboard > Authentication > Users
2. Click your user row to see the UUID
3. Or run: `select id from auth.users where email = 'your@email.com'`

### Development vs Production

**For development:** Use your local development user's ID. This lets you test the permission structure with your existing dev account.

**For production:** Use your production user's ID. The seed creates this account as the root admin with full system access.

## Deploying the Seed

After generating, deploy the seed as a Supabase migration:

1. Create a new migration file:
    - Run the following command:
    ```bash
    pnpm run --filter app supabase migration new supamode-seed
    ```
2. Copy the generated SQL from `apps/app/supabase/seeds/` into the new migration file
3. Test locally by resetting your database
    - Run the following command:
    ```bash
    pnpm run --filter app supabase db reset
    ```

Once tested, deploy to your remote Supabase project. See [Deploying Schema](../deployment/schema) for deployment instructions.

## Template Details

### 1. solo-seed.ts

For solopreneurs and single-developer projects where one person needs complete access.

**What it creates:**

| Component | Details |
|-----------|---------|
| **Role** | Solopreneur (rank 100) |
| **System Permissions** | Full access to accounts, roles, permissions, tables, logs, auth users, system settings |
| **Data Permissions** | All CRUD on public.*, all storage buckets, read auth.users |
| **Permission Group** | "Solopreneur Complete Access" with all permissions |
| **MFA** | Disabled by default |

**Best for:**
- Solo founders
- Single-developer side projects
- Co-founders who share equal access

### 2. small-team-seed.ts

For teams of 3-10 people with clear role separation between admin, developers, and support.

**What it creates:**

| Role | Rank | Capabilities |
|------|------|--------------|
| **Global Admin** | 100 | Full system and data access |
| **Developer** | 80 | Schema/table management, data access, no system settings |
| **Customer Support** | 60 | Read/update customer data, view logs, no system access |

**Best for:**
- Small startups
- Teams needing basic role separation
- Projects with developers and non-technical staff

### 3. saas-seed.ts

Full RBAC structure for larger teams and enterprise applications.

**What it creates:**

| Role | Rank | Permission Group | Key Access |
|------|------|------------------|------------|
| **Root** | 100 | Super Admin | Everything |
| **Admin** | 90 | Administrator | User/role management, all data |
| **Developer** | 80 | Developer | Table config, all data, read system |
| **Manager** | 70 | Manager | All data, read accounts/roles/logs |
| **Support** | 60 | Customer Support | Read/update customer data, read logs |
| **Read Only** | 50 | Read Only | View all data and system info |

**Permission structure:**
- System permissions separated from data permissions
- Each role maps to one permission group
- Clear escalation path through ranks

**Best for:**
- SaaS products with multiple admin tiers
- Companies with compliance requirements
- Teams needing audit trails and role separation

### 4. custom-seed.ts

A blank starting point when you need complete control over your permission structure.

**What it creates:**
- Empty seed file with imports
- No predefined roles or permissions
- You build everything from scratch

**Start here if:**
- Existing templates don't match your needs
- You have unusual permission requirements
- You want to learn the seed generator API

## Customizing Templates

After generating, you can modify the SQL or create a new seed file based on an existing template.

**Common customizations:**
- Add new roles for specific departments
- Create granular permissions for sensitive tables
- Add time-limited roles for contractors
- Define row-level conditions for data access

See the [RBAC System](./rbac) documentation for complete examples of permission patterns.

{% faq
   title="Frequently Asked Questions"
   items=[
     {"question": "Can I switch templates later?", "answer": "Yes, but you'll need to migrate carefully. Generate the new template, compare the SQL, and write a migration that adds new roles/permissions without disrupting existing users. Back up first."},
     {"question": "Do templates include test accounts?", "answer": "The saas-seed template only creates the root account you specify. Add additional test accounts by modifying the seed file before deploying."},
     {"question": "How do I add MFA enforcement?", "answer": "All templates disable MFA by default. After deploying, enable it via Settings > Authentication in the UI, or modify the seed to include: SystemSetting.create({ app, key: 'requires_mfa', value: 'true' })"},
     {"question": "Can two users have the same role?", "answer": "Yes. Roles are reusable. Any number of accounts can share the same role. This is the expected pattern - create roles for job functions, not individuals."},
     {"question": "What if I need a role that combines permissions from multiple templates?", "answer": "Use the custom template and manually add the permissions you need, or start with the closest template and add the missing permissions. Permission groups make this easier - you can create groups that combine capabilities."}
   ]
/%}