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.
const role = { object: 'role', id: 'role_01HXYZ123456789ABCDEFGHIJ', slug: 'admin', name: 'Administrator', description: 'Full access to all resources', type: 'EnvironmentRole', resourceTypeSlug: 'organization', permissions: ['documents:read', 'documents:write', 'users:manage'], createdAt: '2024-01-15T12:00:00.000Z', updatedAt: '2024-01-15T12:00:00.000Z', };
RoleList all environment roles in priority order.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const roles = await workos.authorization.listRoles();
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.
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', });
POST/authorizationReturns Get an environment role by its slug.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const role = await workos.authorization.getRole('admin');
GET/authorizationParameters Returns Update an existing environment role.
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', });
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.
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'], });
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.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const role = await workos.authorization.addRolePermission('editor', { permissionSlug: 'documents:delete', });
POST/authorizationParameters Returns