AuthKit adds support for multiple roles

We’re excited to announce a major enhancement to AuthKit’s Role-Based Access Control (RBAC) system: support for multiple roles per organization membership. This feature gives teams the flexibility they need to model access in a way that reflects how organizations really operate.

Why multiple roles?

Until now, AuthKit enforced a single role per user per organization. While this reduced accidental over-provisioning, it often conflicted with how teams structure access. In real-world scenarios, users frequently span departments or projects and need a union of permissions. Think of a designer who also contributes to engineering, or an analyst who also requires limited admin privileges.

Without multi-role support, teams were forced into awkward workarounds, such as creating "combined roles" (e.g. design-engineering), leading to unnecessary role explosion and complexity.

With multiple roles, access models become easier to design, scale, and maintain. Instead of creating dozens of rigid, one-off roles to cover every possible combination of responsibilities, teams can assign a clean set of atomic roles that reflect their organization’s structure (e.g. Designer, Engineer, Analyst). Users who span responsibilities simply get assigned more than one role, and AuthKit automatically calculates the union of their permissions.

This approach brings several key benefits:

• Clarity in role design: Admins can focus on defining simple, well-bounded roles instead of anticipating every cross-functional need.
• Reduced role sprawl: No more “role explosion” from hybrid roles like design-engineering or analyst-admin.
• Predictable, transparent access: Roles stack additively, so it’s always clear which permissions come from where. For example, instead of inventing a custom marketing-ops role, a user can simply hold Marketing and Ops roles, and the union of their permissions applies.
• Scalability as orgs grow: As organizations add departments or projects, roles can be layered without having to rebuild complex permission structures from scratch.
• Lower maintenance overhead: Fewer roles to manage means less administrative burden and fewer mistakes when provisioning or adjusting access.

In practice, this means RBAC setups are not only easier to get right from the start, but also remain flexible and manageable as your organization evolves.

Use cases

Here’s how teams can use multi-role support:

• Cross-department collaboration: Designers who need engineering permissions, or engineers contributing to product operations.
• Disjoint access needs: Users requiring independent sets of permissions that must be additive.
• Simpler modeling and maintenance: Eliminates the need for hybrid “mega roles” and makes RBAC easier to manage over time, even as organizations grow more complex.

How it works

When enabled, organization memberships can have N roles, with permissions calculated as the union of all assigned roles.

To enable the feature, go to WorkOS dashboard > Roles & Permissions, scroll down to the Multiple roles section, and enable the feature.

Note that for the time being, when multiple roles are enabled, IdP role assignment will be disabled. Compatibility for both features is coming soon.

To edit the roles assigned to a user, head to the WorkOS dashboard > Users, select a user, scroll down to the Organization memberships section, and click Edit roles. Assign the user all the necessary roles.

When a user logs in, the JWT will return a roles array alongside the existing role field.

JWT for single-role (default/off):

	
{
  "role": "admin",
  "permissions": ["perm:a","perm:b"] 
}
	

JWT for multiple roles (enabled):

	
{
  "roles": ["admin","analyst"], 
  "permissions": ["perm:a","perm:b","perm:c"] 
}
	

API responses will include both fields (role and roles) for backward compatibility and to make migration easier. If multiple roles are disabled, the priority order still applies, ensuring no disruption for existing deployments. Eventually, the role field will be deprecated.

Role changes are tracked and logged via the organization_membership.updated event. To see these changes, go to WorkOS dashboard > Events and filter by organization_membership.updated.

Settings & controls

• Multi-role is off by default and must be explicitly enabled.
• It is configured at the Environment level (not per-organization).
• Role assignment through Identity Providers is currently not supported, but it’s coming soon.
• Standalone directory sync and SSO currently don't support multiple roles, but this feature is coming soon.

Looking ahead

This release is a foundational step for AuthKit’s RBAC roadmap. Future updates will expand multi-role support to automated role assignments and improve permission syncing across environments.

Multiple roles in AuthKit are available today. To start configuring roles, head to the Roles & Permissions page on the dashboard. For more information, check out our docs.