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 via organization memberships. Role assignments can be sourced manually or from Identity Provider (IdP) group mappings (SSO or Directory Sync).

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.

AuthKit supports multiple roles per organization membership. A user receives the union of permissions across all assigned roles. For example, a user with the Designer and Engineer roles gets both sets of permissions in their session. This prevents role explosion by avoiding redundant hybrid roles, like “designer-engineer”. Each organization membership must have at least one role.

Multiple roles must be enabled as an environment-level setting; it applies to all organizations in the environment. While enabled, IdP role assignment is not supported, compatibility for both features is coming soon.

Role priority order is used for IdP role assignment to resolve conflicts when a user belongs to multiple mapped groups. The highest-priority role wins. Priority order also determines which role will be assigned to users when migrating from a multiple roles to single role configuration in the environment.

When roles are deleted:

• Single-role (default): All affected organization memberships, SSO profiles, and directory users are reassigned to the default role.
• Multiple-roles: The deleted role is removed from each organization membership that has it, any other roles on the membership remain intact.

Deletion is asynchronous, so updates may take a moment to propagate.

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.