Manage and assign roles and permissions to users.
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.
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.
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.
Permissions allow for more detailed and flexible management of access. They are particularly useful when:
Roles and permissions are managed in the Roles 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.
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, please contact us.
Organization memberships require a role. Every user with an organization membership is automatically assigned the default role when added to an organization. This role can be edited.
You can retrieve the role slug from the user’s organization membership object to determine their access level and capabilities within your application.
When roles are deleted, all organization memberships are reassigned to the default role. Role deletion happens asynchronously, so there may be a slight delay between deleting a role and updating all organization memberships.
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.
If a user is provisioned from multiple sources with conflicting roles, the role with the highest priority will be assigned.
When provisioning users with Directory Sync, allow IT admins to assign roles to groups during directory setup in Admin Portal. This is an environment-level setting. If enabled, all Admin Portal sessions for SCIM-based or Google Workspace directories will have the ability to assign roles to groups.
When a user signs into your app, a user session is initiated. The authentication response includes an access token, a JSON Web Token (JWT), with the “role” claim indicating the organization membership’s role for that session.
Roles can be assigned via SCIM through Identity Provider Role Assignment. Admins can map group membership to roles in the Admin Portal during SCIM and Google Workspace directory setup. These mappings can then be used to set the role on the organization membership via Directory Provisioning.