---
title: Organization Roles
description: Create and manage custom organization-scoped roles
showNextPage: true
originalPath: .tmp-workos-clone/packages/docs/content/rbac/organization-roles.mdx
---

## Overview

Organization roles are custom roles scoped to a particular organization. They are managed via the _Roles_ tab under an organization in the [WorkOS Dashboard](https://dashboard.workos.com/) or using the [Organization Roles API](/reference/roles/organization-role). You can utilize organization roles regardless of whether you're integrating with AuthKit, SSO, or Directory Sync.

![Roles tab for organization](https://images.workoscdn.com/images/5c09cd78-041f-4bb9-9e76-f7267106b22c.png?auto=format&fit=clip&q=50)

### 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.

### Creating organization roles

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 or using the [Organization Roles API](/reference/roles/organization-role/create). All organization role slugs are automatically prefixed with `org`.

![Create an organization role](https://images.workoscdn.com/images/90f3f3c0-3c66-48b2-b962-04b34f30599e.png?auto=format&fit=clip&q=50)

### Organization role configuration

Once you create the first role for an organization, that organization will have its own [default role](/authkit/roles-and-permissions/configure-roles-and-permissions/default-role) and [priority order](/authkit/roles-and-permissions/configure-roles-and-permissions/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.

### Using organization roles

Like environment-level roles, organization roles can be used in [role assignment](/authkit/roles-and-permissions/role-assignment), [sessions](/authkit/roles-and-permissions/role-aware-sessions), and the [organization membership API](/reference/authkit/organization-membership). No additional action is required to enable this behavior after creating organization roles.

### Deleting an environment role

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.

![Select a replacement role](https://images.workoscdn.com/images/5e6f3e51-5de5-4bb1-a850-52b2196282b9.png?auto=format&fit=clip&q=50)