Configuration

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.

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.

Permissions allow for more detailed and flexible management of access. They are particularly useful when:

• You anticipate the need to frequently modify access rights or introduce new roles.
• There is significant overlap in access rights between different roles, but with some variations.
• You want to minimize code changes when modifying access rights. By abstracting access control checks to permissions, you can add or modify roles and their access rights without changing the application code.

You can manage permissions in the Roles & Permissions section of the WorkOS Dashboard.

When configuring permissions, we recommend:

• Defining a common naming scheme to use across all permissions for your application. Consider separating the resource and action with a delimiter, such as users:view. The following delimiters are permitted: -.:_*.
• Keep permission slugs clear and concise. When assigned to roles, these slugs will included as part of session cookies in the session JWT claims, which is limited to a maximum size of 4KB in many modern web browsers.

Permissions can be assigned when creating a new role or when editing an existing role.