An organization role is an access control resource defined at the organization level. Organization roles allow individual organizations to create custom roles tailored to their specific needs, in addition to the environment roles that apply across all organizations.
Like environment roles, organization roles can be assigned to organization memberships, directory users, and SSO profiles. Each organization role has a unique slug identifier within the organization and can have permissions assigned to it.
When listing roles for an organization, both environment roles and organization roles are returned in priority order. Environment roles are included because they apply to all organizations in your environment.
{ "object": "role", "id": "role_01HXYZ123456789ABCDEFGHIJ", "slug": "org-billing-admin", "name": "Billing Administrator", "description": "Can manage billing and invoices", "type": "OrganizationRole", "permissions": ["billing:read", "billing:write", "invoices:manage"], "created_at": "2024-01-15T12:00:00.000Z", "updated_at": "2024-01-15T12:00:00.000Z" }
Organization RoleGet a list of all roles that apply to an organization. This includes both environment roles and organization-specific roles, returned in priority order.
curl --request GET \ --url https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles \ --header "Authorization: Bearer sk_example_123456789"
GET/authorizationReturns objectCreate a new custom organization role. The role will be specific to the organization and can be assigned to organization memberships.
The slug must be unique within the organization, begin with org-, and contain only lowercase letters, numbers, hyphens, and underscores.
New roles are placed at the bottom of the organization’s priority order.
curl --request POST \ --url https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "slug": "org-billing-admin", "name": "Billing Administrator", "description": "Can manage billing and invoices" } BODY
Retrieve a role that applies to an organization by its slug. This can return either an environment role or an organization-specific role.
curl --request GET \ --url https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-billing-admin \ --header "Authorization: Bearer sk_example_123456789"
GET/authorizationReturns Update an existing custom organization role. Only the fields provided in the request body will be updated.
curl --request PATCH \ --url https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-billing-admin \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "name": "Finance Administrator", "description": "Can manage all financial operations" } BODY
Delete an existing custom organization role. The role must not have any active assignments or IdP group role mappings.
If the role has active assignments, you will receive a 409 Conflict error with code role_has_assignments. If the role has group role mappings, you will receive a 409 Conflict error with code role_has_group_role_mappings.
curl --request DELETE \ --url https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-billing-admin \ --header "Authorization: Bearer sk_example_123456789"
DELETE/authorizationReplace all permissions assigned to an organization role. This operation removes any existing permissions and assigns the provided permissions.
To remove all permissions from a role, pass an empty array.
curl --request PUT \ --url https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-billing-admin/permissions \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "permissions": ["billing:read", "billing:write", "invoices:manage", "reports:view"] } BODY
Add a single permission to an organization role. If the permission is already assigned to the role, this operation has no effect.
curl --request POST \ --url https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-billing-admin/permissions \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "slug": "reports:export" } BODY
Remove a single permission from an organization role by its slug.
curl --request DELETE \ --url https://api.workos.com/authorization/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/roles/org-billing-admin/permissions/reports:export \ --header "Authorization: Bearer sk_example_123456789"
DELETE/authorizationReturns