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.

Overview

While the static RBAC configuration 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 NEXT_PUBLIC_ENABLE_CUSTOM_ROLES environment variable to true.

NEXT_PUBLIC_ENABLE_CUSTOM_ROLES=true

This feature is disabled by default.

Accessing Roles Management

Navigate to Settings → Roles to manage custom roles.

• Route: /settings/roles
• Permissions: Requires ac:read permission (admin or owner)

Default Roles

Three roles come pre-configured and cannot be modified:

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:

Permission Matrix

The permission matrix provides fine-grained control:

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

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:

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

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

Related Documentation

• Roles & Permissions — Static RBAC configuration
• Permissions API — Server-side permission checking
• Invitations — Member invitation workflow