Custom Roles
Overview
Custom Roles allow you to create tailored permission sets beyond the four built-in default roles. Instead of fitting every user into a predefined role, you can define exactly what each group of users can access and manage across your tenant.
Custom Roles are managed from the Admin Dashboard under the Custom Roles page within each tenant.
Who This Is For
Client Admins who need granular control over user permissions
Organizations with specific security or compliance requirements
Teams that need permission sets not covered by default roles
Admins managing multiple user types with varying access needs
Prerequisites
Access to the Admin Dashboard
The Manage User Roles permission (typically included in the Client Admin default role)
An active tenant
Understanding Default Roles vs. Custom Roles
Default Roles
Every tenant includes four built-in default roles with fixed permissions:
Default Role | Description |
Client Admin | Full access to tenant settings, user management, Workshop, Phone Agents, and all platform features |
General User | Standard access to Chat, Workshop items, and core platform features |
Workshop User | Access to Workshop (viewing and creating items) plus Chat |
Chat Only User | Minimal access limited to AI Chat only |
Default roles cannot be edited or deleted. Their permissions are fixed by the platform.
Custom Roles
Custom roles provide flexibility to:
Select individual permissions from the full permission catalog
Create descriptive, meaningful role names
Set optional per-user monthly credit limits
Assign the role to any number of users
Available Permissions
Permissions are organized into categories for easier management:
Category | Permission | Description |
Basic Access | Access Chat | Use AI Chat |
| User Settings | Access personal user settings |
| Create API Token | Create personal API tokens |
Workshop | View Workshop Items | View and run items in Workshop |
| Create Workshop Items | Create items in Workshop |
| Delete Workshop Items | Delete items from Workshop |
| Duplicate Workshop Items | Duplicate items in Workshop |
AI Phone Agent | View Phone Agents | View AI phone agents |
| Manage Phone Agents | Configure and manage AI phone agents |
Administration | Manage Users | Invite and manage users in the tenant |
| Manage Tenant User Roles | Manage user roles in child tenants |
| Create Groups | Create sharing groups |
| Manage Groups | Edit, delete, and manage membership of sharing groups |
| Share with Groups | Share apps and agents with groups |
| Manage Own Integrations | Manage integrations as a client admin |
| Manage Email Templates | Manage email templates for the tenant |
| Tenant LLM Control | Enable or disable LLMs for the tenant |
| Manage Tenant MFA | Configure MFA settings for the tenant |
| Manage Tenant Memory | Configure memory settings for the tenant |
| Manage Tenant Personalization | Configure personalization settings for the tenant |
| Manage Tenant Branding | Configure tenant branding and white-label settings |
| View Usage & Limits | View usage data and credit limits |
Other | Various | Additional permissions not categorized above (such as SAML or billing-related permissions) |
Creating a Custom Role
Steps
Navigate to the Admin Dashboard and select your tenant
Open Custom Roles from the tenant sidebar
Click New Custom Role
Configure role details:
Display Name (required) -- Enter a unique name up to 100 characters
Description (optional) -- Add context up to 500 characters
Monthly Credit Limit (optional) -- Set a per-user spending cap, or leave blank for no limit
Select permissions:
Option A: Choose Start from a default role to pre-fill permissions, then customize
Option B: Build from scratch by selecting individual permissions
Use the search function or group-level checkboxes to quickly select categories
Click Create Role
Expected Results
The new custom role appears in the Custom Roles table and becomes available in the role dropdown when managing users.
Managing Users with Custom Roles
Assigning Users to a Custom Role
Method 1 - From Custom Roles table:
Click the Users icon on the role row
Click Add Users
Search for and select users
Confirm assignment
Method 2 - From Users & Roles:
Open the role dropdown for any user
Select the custom role from the Custom Roles group
Bulk Reassignment
From the Custom Roles user management modal:
Select multiple users using checkboxes
Choose a target role (custom or default)
Confirm the bulk reassignment
All selected users are moved to the new role simultaneously.
Removing Users from a Custom Role
Reassign the user to a different role (custom or default). Users must always have exactly one platform role assigned.
Editing a Custom Role
Editing Role Details
Click the Settings icon on the role row
Update the display name, description, or credit limit
Save changes
Editing Permissions
Click the Permissions icon on the role row
The permission picker highlights which permissions will be added or removed
Make your changes
Save to apply
Permission changes take effect immediately for all users assigned to the role.
Deleting a Custom Role
Click the Delete icon on the role row
A confirmation dialog appears
Important: You cannot delete a custom role while users are assigned to it. First reassign all users to a different role, then delete the custom role.
Credit Limits (coming soon)
Each custom role supports an optional monthly credit limit that applies per user. This cap controls AI usage spending (Chat, Phone Agents, etc.) for each user in that role individually.
If no credit limit is set, users in that role have unlimited credit access.
Role Comparison
You can compare permissions across up to 10 roles (both default and custom) using the role comparison feature available via API. This is useful for auditing access differences and ensuring appropriate permission distribution.
Troubleshooting
Issue: Cannot delete a custom role
Solution: Check if any users are assigned to the role. Reassign all users to a different role before attempting deletion.
Issue: Cannot save a custom role with a duplicate name
Solution: Each custom role must have a unique display name within the tenant. Choose a different name.
Issue: Permission changes not reflecting
Solution: Permission changes are immediate. If users don't see expected access, verify they are assigned to the correct role and have logged out and back in if necessary.
Issue: Cannot find the Custom Roles page
Solution: Verify you are accessing the Admin Dashboard (not the tenant user view) and have the Manage User Roles permission.
Limitations
Admin Dashboard access required - Custom roles can only be created, edited, and deleted from the Admin Dashboard. End users in the tenant view cannot manage roles.
Cannot delete roles with active users - All users must be reassigned to a different role before a custom role can be deleted.
Unique names per tenant - Each custom role display name must be unique within its tenant. Duplicate names are not allowed.
No role hierarchy - Permissions are flat and additive. Custom roles do not inherit permissions from other roles. A custom role contains exactly the permissions you assign to it.
One role per user per tenant - Each user can hold exactly one platform role (default or custom) per tenant. Multiple simultaneous platform roles are not supported.
Character limits - Display names are limited to 100 characters. Descriptions are limited to 500 characters.
Immediate permission changes - When you update a custom role's permissions, the changes apply immediately to all users assigned to that role. There is no grace period or delayed enforcement.
Per-user credit limits - The monthly credit limit set on a custom role applies individually to each user in the role. It is not a shared pool across all users.
Default roles are immutable - The four built-in default roles (Client Admin, General User, Workshop User, Chat Only User) cannot be edited or deleted.
Permission visibility - Only user-selectable permissions appear in the permission picker. Internal, system-level, and legacy permissions are hidden and cannot be assigned to custom roles.
SCIM provisioning compatibility - Custom roles can be set as the default role for SCIM provisioning. New users provisioned via SSO will automatically receive the designated custom role.
Migration from Permission Groups - If your tenant previously used the legacy Permission Groups feature, those can be migrated to custom roles. Custom roles are the recommended replacement going forward.