Customizing Roles and Permissions

Adding a new permission

Step 1: Add the permission constant to Permissions.cs in Domain:

// src/Acme.Domain/Constants/Permissions.cs
public static class Permissions
{
    // existing permissions...
    public const string TenantProjectsRead = "tenant.projects.read";
    public const string TenantProjectsManage = "tenant.projects.manage";
}

Step 2: Add the new permissions to the appropriate built-in roles in GetPermissionsForRole():

// src/Acme.Domain/Services/RolePermissionService.cs
public static IReadOnlyList<string> GetPermissionsForRole(string roleName)
{
    return roleName switch
    {
        RoleNames.Owner => new[]
        {
            // all existing permissions...
            Permissions.TenantProjectsRead,
            Permissions.TenantProjectsManage,
        },
        RoleNames.Admin => new[]
        {
            // existing admin permissions...
            Permissions.TenantProjectsRead,
            Permissions.TenantProjectsManage,
        },
        RoleNames.Member => new[]
        {
            // existing member permissions...
            Permissions.TenantProjectsRead,
            // Members cannot manage projects by default
        },
        _ => Array.Empty<string>()
    };
}

Step 3: Apply the [HasPermission] attribute to controller actions that require the new permission:

[HttpPost]
[HasPermission(Permissions.TenantProjectsManage)]
public async Task<IActionResult> CreateProject([FromBody] CreateProjectRequest request)
{
    // ...
}

[HttpGet]
[HasPermission(Permissions.TenantProjectsRead)]
public async Task<IActionResult> GetProjects()
{
    // ...
}

Step 4: Update the frontend usePermissions() hook usage and command palette to show/hide items based on the new permission:

<PermissionGate permission={Permissions.TenantProjectsManage}>
  <CreateProjectButton />
</PermissionGate>

Creating custom roles via the API

Any tenant member with the tenant.roles.manage permission can create custom roles:

POST /api/v1/tenants/current/roles
Authorization: Bearer <token>

{
  "name": "Developer",
  "permissions": [
    "tenant.settings.read",
    "tenant.members.read",
    "tenant.projects.read",
    "tenant.projects.manage"
  ]
}

Updating a custom role:

PUT /api/v1/tenants/current/roles/{roleId}
Authorization: Bearer <token>

{
  "name": "Senior Developer",
  "permissions": [
    "tenant.settings.read",
    "tenant.members.read",
    "tenant.members.invite",
    "tenant.projects.read",
    "tenant.projects.manage"
  ]
}

Deleting a custom role:

DELETE /api/v1/tenants/current/roles/{roleId}
Authorization: Bearer <token>

Deleting a role that has members assigned to it fails with a CONFLICT error. Reassign all members to a different role before deleting.

Permission change propagation

Permissions are embedded in the JWT access token. If you change a role’s permissions — either by editing GetPermissionsForRole() in code or by updating a custom role via the API — affected users continue using the old permissions until their current access token expires (up to 15 minutes) and they get a new one via refresh.There is no built-in mechanism to immediately revoke access tokens for a specific role change. For permission removals that must take effect immediately, the only option is to force re-authentication for the affected users.

Limitations

You cannot use built-in role names (Owner, Admin, Member) for custom roles.
A role must have at least one permission.
Permission strings must exactly match constants in Permissions.cs. Invalid strings are rejected with a validation error.
The Owner role cannot be deleted or modified. It always has all permissions.
Each tenant can have at most one Owner.

Getting Started

Core Concepts

Configuration

Guides

Deployment

Reference

Customizing Roles and Permissions

Adding a new permission

Creating custom roles via the API

Permission change propagation

Limitations

​Adding a new permission

​Creating custom roles via the API

​Permission change propagation

​Limitations

Adding a new permission

Creating custom roles via the API

Permission change propagation

Limitations