Organization Roles
Create and manage custom organization-scoped roles
Organization roles are custom roles scoped to a particular organization. They are managed via the Roles tab under an organization in the WorkOS Dashboard. You can utilize organization roles regardless of whether you’re integrating with AuthKit, SSO, or Directory Sync.
Why might I use organization roles?
In some cases, an application’s fixed set of roles may not meet the needs of certain organizations. For example, an organization may require a lesser privileged set of permissions for their members. Organization roles allow you to create custom roles, with the organization’s desired set of permissions, without affecting access control for other organizations.
By default, organizations have no custom organization roles and simply inherit the environment-level roles. You can create an organization role by clicking the “Create role” button on the organization’s Roles tab. All organization role slugs are automatically prefixed with org.
Once you create the first role for an organization, that organization will have its own default role and priority order, independent from the environment.
New roles added to the environment will be available to the organization and placed at the bottom of the organization’s role priority order.
Like environment-level roles, organization roles can be used in role assignment, sessions, and the organization membership API. No additional action is required to enable this behavior after creating organization roles.
When attempting to delete an environment role that’s the default role for one or more organizations, you’ll be prompted to select a new default role for all affected organizations. Organization members previously assigned the deleted role will be assigned the new organization default role.
