An environment role is an access control resource defined at the environment level. Environment roles can be assigned to organization memberships, directory users, and SSO profiles.
Environment roles provide a consistent set of roles across all organizations in your environment. Each role has a unique slug identifier. Roles can have permissions assigned to them.
List all environment roles in priority order.
curl "https://api.workos.com/authorization/roles" \ --header "Authorization: Bearer sk_example_123456789"
{ "object": "list", "data": [ { "slug": "admin", "object": "role", "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", "name": "Admin", "description": "Can manage all resources", "type": "EnvironmentRole", "resource_type_slug": "organization", "permissions": [ "posts:read", "posts:write" ], "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" } ] }
| curl "https://api.workos.com/authorization/roles" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const roles = await workos.authorization.listRoles(); |
| from workos import WorkOSClient | |
| workos_client = WorkOSClient( | |
| api_key="sk_example_123456789", client_id="client_123456789" | |
| ) | |
| roles = workos_client.authorization.list_roles() |
| { | |
| "object": "list", | |
| "data": [ | |
| { | |
| "slug": "admin", | |
| "object": "role", | |
| "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "name": "Admin", | |
| "description": "Can manage all resources", | |
| "type": "EnvironmentRole", | |
| "resource_type_slug": "organization", | |
| "permissions": [ | |
| "posts:read", | |
| "posts:write" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } | |
| ] | |
| } |
GET/authorizationReturns Create a new environment role.
The slug must be unique across all environment roles and can only contain lowercase letters, numbers, hyphens, and underscores.
New roles are placed at the bottom of the priority order.
curl --request POST \ --url "https://api.workos.com/authorization/roles" \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<'BODY' { "slug": "editor", "name": "Editor", "description": "Can edit resources" } BODY
{ "slug": "editor", "object": "role", "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", "name": "Editor", "description": "Can edit resources", "type": "EnvironmentRole", "resource_type_slug": "organization", "permissions": [ "posts:read", "posts:write" ], "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" }
| curl --request POST \ | |
| --url "https://api.workos.com/authorization/roles" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "slug": "editor", | |
| "name": "Editor", | |
| "description": "Can edit resources" | |
| } | |
| BODY |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const role = await workos.authorization.createRole({ | |
| slug: 'editor', | |
| name: 'Editor', | |
| description: 'Can edit and publish content', | |
| }); |
| from workos import WorkOSClient | |
| workos_client = WorkOSClient( | |
| api_key="sk_example_123456789", client_id="client_123456789" | |
| ) | |
| role = workos_client.authorization.create_role( | |
| slug="editor", | |
| name="Editor", | |
| description="Can edit and publish content", | |
| ) |
| { | |
| "slug": "editor", | |
| "object": "role", | |
| "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "name": "Editor", | |
| "description": "Can edit resources", | |
| "type": "EnvironmentRole", | |
| "resource_type_slug": "organization", | |
| "permissions": [ | |
| "posts:read", | |
| "posts:write" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
POST/authorizationReturns Get an environment role by its slug.
curl "https://api.workos.com/authorization/roles/admin" \ --header "Authorization: Bearer sk_example_123456789"
{ "slug": "admin", "object": "role", "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", "name": "Admin", "description": "Can manage all resources", "type": "EnvironmentRole", "resource_type_slug": "organization", "permissions": [ "posts:read", "posts:write" ], "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" }
| curl "https://api.workos.com/authorization/roles/admin" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const role = await workos.authorization.getRole('admin'); |
| from workos import WorkOSClient | |
| workos_client = WorkOSClient( | |
| api_key="sk_example_123456789", client_id="client_123456789" | |
| ) | |
| role = workos_client.authorization.get_role(slug="admin") |
| { | |
| "slug": "admin", | |
| "object": "role", | |
| "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "name": "Admin", | |
| "description": "Can manage all resources", | |
| "type": "EnvironmentRole", | |
| "resource_type_slug": "organization", | |
| "permissions": [ | |
| "posts:read", | |
| "posts:write" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
GET/authorizationParameters Returns Update an existing environment role.
curl --request PATCH \ --url "https://api.workos.com/authorization/roles/admin" \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<'BODY' { "name": "Super Administrator", "description": "Full administrative access to all resources" } BODY
{ "slug": "admin", "object": "role", "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", "name": "Super Administrator", "description": "Full administrative access to all resources", "type": "EnvironmentRole", "resource_type_slug": "organization", "permissions": [ "posts:read", "posts:write" ], "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" }
| curl --request PATCH \ | |
| --url "https://api.workos.com/authorization/roles/admin" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "name": "Super Administrator", | |
| "description": "Full administrative access to all resources" | |
| } | |
| BODY |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const role = await workos.authorization.updateRole('admin', { | |
| name: 'Super Administrator', | |
| description: 'Full administrative access to all resources', | |
| }); |
| from workos import WorkOSClient | |
| workos_client = WorkOSClient( | |
| api_key="sk_example_123456789", client_id="client_123456789" | |
| ) | |
| role = workos_client.authorization.update_role( | |
| slug="admin", | |
| name="Super Administrator", | |
| description="Full administrative access to all resources", | |
| ) |
| { | |
| "slug": "admin", | |
| "object": "role", | |
| "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "name": "Super Administrator", | |
| "description": "Full administrative access to all resources", | |
| "type": "EnvironmentRole", | |
| "resource_type_slug": "organization", | |
| "permissions": [ | |
| "posts:read", | |
| "posts:write" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
PATCH/authorizationParameters Returns Replace all permissions assigned to an environment 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/roles/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
{ "slug": "admin", "object": "role", "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", "name": "Admin", "description": "Can manage all resources", "type": "EnvironmentRole", "resource_type_slug": "organization", "permissions": [ "billing:read", "billing:write", "invoices:manage", "reports:view" ], "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" }
| curl --request PUT \ | |
| --url "https://api.workos.com/authorization/roles/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 |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const role = await workos.authorization.setRolePermissions('editor', { | |
| permissions: ['documents:read', 'documents:write', 'documents:publish'], | |
| }); |
| from workos import WorkOSClient | |
| workos_client = WorkOSClient( | |
| api_key="sk_example_123456789", client_id="client_123456789" | |
| ) | |
| role = workos_client.authorization.set_role_permissions( | |
| slug="editor", | |
| permissions=["documents:read", "documents:write", "documents:publish"], | |
| ) |
| { | |
| "slug": "admin", | |
| "object": "role", | |
| "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "name": "Admin", | |
| "description": "Can manage all resources", | |
| "type": "EnvironmentRole", | |
| "resource_type_slug": "organization", | |
| "permissions": [ | |
| "billing:read", | |
| "billing:write", | |
| "invoices:manage", | |
| "reports:view" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
PUT/authorizationParameters Returns Add a single permission to an environment role. If the permission is already assigned to the role, this operation has no effect.
curl --request POST \ --url "https://api.workos.com/authorization/roles/admin/permissions" \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<'BODY' { "slug": "reports:export" } BODY
{ "slug": "admin", "object": "role", "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", "name": "Admin", "description": "Can manage all resources", "type": "EnvironmentRole", "resource_type_slug": "organization", "permissions": [ "reports:export" ], "created_at": "2026-01-15T12:00:00.000Z", "updated_at": "2026-01-15T12:00:00.000Z" }
| curl --request POST \ | |
| --url "https://api.workos.com/authorization/roles/admin/permissions" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "slug": "reports:export" | |
| } | |
| BODY |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const role = await workos.authorization.addRolePermission('editor', { | |
| permissionSlug: 'documents:delete', | |
| }); |
| from workos import WorkOSClient | |
| workos_client = WorkOSClient( | |
| api_key="sk_example_123456789", client_id="client_123456789" | |
| ) | |
| role = workos_client.authorization.add_role_permission( | |
| slug="editor", | |
| permission_slug="documents:delete", | |
| ) |
| { | |
| "slug": "admin", | |
| "object": "role", | |
| "id": "role_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "name": "Admin", | |
| "description": "Can manage all resources", | |
| "type": "EnvironmentRole", | |
| "resource_type_slug": "organization", | |
| "permissions": [ | |
| "reports:export" | |
| ], | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
POST/authorizationParameters Returns