Organization-Specific Custom Roles
Scalekit now supports organization-specific custom roles, allowing your customers to create roles tailored to their unique organizational structure. Organization admins can define custom roles that extend beyond your application's default roles for more flexible access control.
Many B2B applications let their customers configure custom roles for their specific organization. For example, an organization might need a "Project Manager" role that combines permissions from multiple default roles, or a "Regional Admin" role that doesn't exist in your standard role set. Previously, you could only configure roles at the environment level, meaning all organizations shared the same role structure.
With organization-specific roles, each customer can create roles that match their internal hierarchy and access policies — giving them greater flexibility and control.
How it works
Organization admins create custom roles
From the Scalekit dashboard or API, organization admins define custom roles with display names, machine-friendly identifiers (keys), and descriptions of what users with that role can do.
Roles extend base permissions
Custom roles can extend existing roles and include specific permissions. For example, a "Project Manager" role might extend the "editor" role and add permissions like projects:manage and users:invite.
Token claims include roles and permissions
Access tokens contain both roles and permissions claims. ID tokens contain the roles claim. Roles appear as their key (not display name), and permissions appear as their identifier (not description).
Fallback to environment roles
If an organization has no custom roles configured, it falls back to environment-level roles for role assignment.
.png)
What's included
Dashboard Configuration
Create and manage organization-specific roles directly from Organizations > Roles > Custom Role section. Provide display name, key, description, and permissions.
API Management
Programmatically create, update, list, and retrieve organization-specific roles using the Scalekit API. Perfect for syncing roles from your application's admin panel.
Role Inheritance
Custom roles can extend base roles using the extends parameter, automatically inheriting all permissions from the parent role.
Permission Assignment
Specify direct permissions for each role. Inherited permissions from base roles are automatically included in tokens and API responses.
Default Role Designation
Mark one role as the default for users without an assigned custom role.
Token Claims
Roles and permissions appear in tokens for authorization checks in your backend and UI. Access tokens include both claims; ID tokens include roles only.
Use cases
Match customer organizational structures
Create roles that align with how your customers organize their teams internally, like "Regional Manager" or "Department Lead."
Combine permissions flexibly
Build roles that span multiple permission sets from your default roles, giving customers granular control without cluttering your application's role model.
Industry-specific roles
Support customers in different industries with specialized roles like "Compliance Officer," "Audit Manager," or "Safety Coordinator."
Hierarchical access control
Enable customers to define tiered access levels that match their approval workflows and reporting structures.
Configuration
Via Dashboard:
- Navigate to Organizations in your Scalekit Dashboard
- Select the organization you want to configure
- Go to the Roles tab
- In the Custom Role section, click + Add role
- Provide:
- Display name: Human-readable name (e.g., "Project Manager")
- Name (key): Machine-friendly identifier (e.g.,
project_manager) - Description: Clear explanation of role capabilities
- Extends (optional): Base role to inherit from
- Permissions: List of permission identifiers
Get started
Organization-specific custom roles are available now as part of Scalekit's Full-Stack Auth:
- Configure in your dashboard
- View documentation
- Contact support for configuration assistance
