A role assignment connects an organization membership to a role on a specific resource. When a role is assigned, the user gains all permissions included in that role on the resource and its descendants through permission inheritance.
const roleAssignment = { object: 'role_assignment', id: 'role_assignment_01HXYZ123456789ABCDEFGH', role: { slug: 'editor', }, resource: { id: 'authz_resource_01HXYZ123456789ABCDEFGH', externalId: 'proj-456', resourceTypeSlug: 'project', }, createdAt: '2025-01-15T14:30:00.000Z', updatedAt: '2025-01-15T14:30:00.000Z', };
RoleAssignmentList all role assignments for an organization membership. This returns all resource-scoped roles that have been assigned to the user.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const roleAssignments = await workos.authorization.listRoleAssignments({ organizationMembershipId: 'om_01HXYZ123456789ABCDEFGHIJ', });
authorizationParameters objectReturns objectAssign a role to an organization membership on a specific resource. The user will immediately gain all permissions included in that role on the resource and its descendants.
You must provide either resource_id or both resource_external_id and resource_type_slug to identify the resource.
The role must be scoped to the resource type of the target resource. You cannot assign a project role on a workspace resource.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); // Option 1: by resource ID const roleAssignment = await workos.authorization.assignRole({ organizationMembershipId: 'om_01HXYZ123456789ABCDEFGHIJ', roleSlug: 'editor', resourceId: 'authz_resource_01HXYZ123456789ABCDEFGH', }); // Option 2: by external ID + type const roleAssignmentByExternal = await workos.authorization.assignRole({ organizationMembershipId: 'om_01HXYZ123456789ABCDEFGHIJ', roleSlug: 'editor', resourceExternalId: 'proj-456', resourceTypeSlug: 'project', });
authorizationParameters objectReturns Remove a role assignment by specifying the role slug and resource. Access is revoked immediately. Removing an assignment also removes any permissions that were inherited by child resources through that assignment.
You must provide either resource_id or both resource_external_id and resource_type_slug to identify the resource.
This removes the specific role assignment, but direct assignments on child resources remain intact.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); // Option 1: by resource ID await workos.authorization.removeRole({ organizationMembershipId: 'om_01HXYZ123456789ABCDEFGHIJ', roleSlug: 'editor', resourceId: 'authz_resource_01HXYZ123456789ABCDEFGH', }); // Option 2: by external ID + type await workos.authorization.removeRole({ organizationMembershipId: 'om_01HXYZ123456789ABCDEFGHIJ', roleSlug: 'editor', resourceExternalId: 'proj-456', resourceTypeSlug: 'project', });
authorizationParameters objectReturns Remove a role assignment using its ID. Access is revoked immediately. Removing an assignment also removes any permissions that were inherited by child resources through that assignment.
This removes the specific role assignment, but direct assignments on child resources remain intact.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); await workos.authorization.removeRoleAssignment({ organizationMembershipId: 'om_01HXYZ123456789ABCDEFGHIJ', roleAssignmentId: 'role_assignment_01HXYZ123456789ABCDEFGH', });
authorizationParameters objectReturns