Configure roles and permissions
A role represents a logical grouping of permissions, defining access control levels for users within your application. Roles are identified by unique, immutable slugs and are assigned to users through organization memberships, SSO profiles, and directory users.
Permissions grant users privileged access to resources and actions in your application and are referenced in your code by unique, immutable slugs. A permission can be assigned to any number of roles.
Role and permission configuration is relevant for all integrations.
Roles alone can be sufficient when your application only requires very coarse-grained access control. This is suitable if users only need to be separated into broad categories and there is minimal overlap between roles. Simple roles can be easier to manage, but are less flexible for complex access control scenarios.
You can manage roles in the Roles & Permissions section of the WorkOS Dashboard.
Role slugs are immutable and cannot be changed after creation. Environment role slugs are unique within an environment. Organization role slugs are unique within an organization.
Role configuration occurs at the environment level. Each environment is seeded with a default member
role, which is automatically assigned to every organization member. This default role cannot be deleted, but any role can be set as the default.
If you need to set default roles or other role configurations at the organization level, refer to the Organization roles section.
Role priority order is used for Identity Provider (IdP) role assignment and determines which role is assigned when a user is a member of multiple groups that contain conflicting role mappings. For example, there might be a case where an employee Jane is an Engineering Manager and belongs to the “Engineering”, “Manager”, and “Admin” groups. In that scenario, the role with the highest priority will be assigned.
When roles are deleted, all affected organization memberships, SSO profiles, and directory users are reassigned to the default role. Role deletion happens asynchronously, so there may be a slight delay between deleting a role and updating affected role assignments.
To migrate from one default role to another, set the new default role and delete the old one. All users will then be reassigned to the new default role.
Permissions allow for more detailed and flexible management of access. They are particularly useful when:
You can manage permissions in the Roles & Permissions section of the WorkOS Dashboard.
When configuring permissions, we recommend:
users:view
. The following delimiters are permitted: -.:_*
.Permissions can be assigned when creating a new role or when editing an existing role.