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.
{ "object": "role", "id": "role_01HXYZ123456789ABCDEFGHIJ", "slug": "admin", "name": "Administrator", "description": "Full access to all resources", "type": "EnvironmentRole", "permissions": ["documents:read", "documents:write", "users:manage"], "created_at": "2024-01-15T12:00:00.000Z", "updated_at": "2024-01-15T12:00:00.000Z" }
RoleGet a list of all environment roles. Roles are returned in priority order.
curl https://api.workos.com/authorization/roles \ --header "Authorization: Bearer sk_example_123456789"
GET/authorizationReturns objectCreate 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 and publish content" } BODY
Retrieve an environment role by its unique slug.
curl https://api.workos.com/authorization/roles/admin \ --header "Authorization: Bearer sk_example_123456789"
Update an existing environment role. Only the fields provided in the request body will be updated.
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
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/editor/permissions \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "permissions": ["documents:read", "documents:write", "documents:publish"] } BODY
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/editor/permissions \ --header "Authorization: Bearer sk_example_123456789" \ --header "Content-Type: application/json" \ -d @- <<BODY { "slug": "documents:delete" } BODY