# Custom Roles

> Create and manage organization-specific roles through the UI.

*Canonical: https://makerkit.dev/docs/tanstack-prisma/members-management/custom-roles*

---

Custom roles allow organizations to create roles tailored to their specific needs without modifying code. Each organization can define its own roles with custom permissions. This feature ships with the [Prisma](/prisma) kit.

## Overview

While the [static RBAC configuration](./roles-permissions) defines app-wide roles, custom roles are:
- Created per-organization through the UI
- Stored in the database
- Configurable without deployments

## Enabling Custom Roles

To enable custom roles, you need to set the `VITE_ENABLE_CUSTOM_ROLES` environment variable to `true`.

```bash {% title="apps/web/.env" %}
VITE_ENABLE_CUSTOM_ROLES=true
```

This feature is disabled by default. The flag is read into `featuresFlag.enableCustomRoles` (`apps/web/src/config/feature-flags.config.ts`), and the `/settings/roles` route redirects away when it is off.

## Accessing Roles Management

Navigate to **Settings → Roles** to manage custom roles.

- **Route:** `/settings/roles`
- **Permissions:** Requires `ac:update` permission

## Default Roles

Three roles come pre-configured and cannot be modified:

| Role | Level | Description |
|------|-------|-------------|
| Owner | 100 | Full organization control |
| Admin | 50 | Manage members and settings |
| Member | 10 | Basic access |

## Creating Custom Roles

Click **Create Role** to add a new custom role:

1. **Name** — Unique identifier (lowercase, hyphens allowed)
2. **Position** — Where in hierarchy relative to default roles
3. **Description** — Optional explanation of the role's purpose
4. **Permissions** — Configure via the Permission Matrix

### Position Options

Custom roles are inserted relative to existing roles:

| Position | Hierarchy Level | Permissions Template |
|----------|----------------|---------------------|
| Above Admin | 75 | Admin-level |
| Between Admin and Member | 30 | Member-level |
| Below Member | 5 | Member-level |

### Permission Matrix

The permission matrix provides fine-grained control:

| Resource | Available Actions |
|----------|-------------------|
| Organization | read, update, delete |
| Member | create, read, update, delete |
| Invitation | create, read, update, delete, cancel |
| Billing | read, update |
| Access Control | read |

Check the actions to grant for each resource.

## Viewing Role Details

Click the **View** action to see a role's complete permission configuration in a read-only dialog.

## Editing Custom Roles

Click **Edit** from the actions menu to modify:
- Role name
- Description
- Permission assignments

**Note:** Default roles (owner, admin, member) cannot be edited.

## Deleting Custom Roles

To delete a custom role:

1. Ensure no members are assigned the role
2. Click **Delete** from the actions menu
3. Confirm the deletion

If members are assigned to the role, reassign them first.

## Using Custom Roles

Once created, custom roles appear automatically in:
- **Invitation dialog** — Assign role when inviting members
- **Update role dialog** — Change existing member roles
- **Members table** — Role badges display correctly

## Static vs Dynamic Roles

| Aspect | Static Config | Custom Roles |
|--------|--------------|--------------|
| Defined in | `rbac.config.ts` | Database |
| Scope | All organizations | Per-organization |
| Requires deploy | Yes | No |
| Best for | App-wide roles | Organization-specific needs |

Both approaches can be used together. Static roles provide the foundation, while custom roles offer flexibility.

## Server-Side Integration

Custom roles integrate with the existing permission system:

```typescript
import { getRequestHeaders } from '@tanstack/react-start/server';

// Check permissions - works with custom roles
const { success: canInvite } = await auth.api.hasPermission({
  headers: getRequestHeaders(),
  body: {
    permissions: { invitation: ['create'] },
  },
});
```

The `canTargetRole` function also supports custom roles when provided the organization's role hierarchy.

## Related Documentation

- [Roles & Permissions](./roles-permissions) — Static RBAC configuration
- [Permissions API](./permissions-api) — Server-side permission checking
- [Invitations](./invitations) — Member invitation workflow