The Authorization API provides a comprehensive role-based access control (RBAC) system with support for environment roles, organization roles, permissions, resources, and role assignments.
Initialize import { WorkOS } from '@workos-inc/node' ; const workos = new WorkOS ( 'sk_example_123456789' );
Environment Roles Environment roles are global roles that apply across your entire WorkOS environment.
createEnvironmentRole Create a new environment role.
const role = await workos . authorization . createEnvironmentRole ({ slug: 'admin' , name: 'Administrator' , description: 'Full system access' , resourceTypeSlug: 'project' , permissions: [ 'read' , 'write' , 'delete' ], });
options
CreateEnvironmentRoleOptions
required
Unique identifier for the role.
Display name of the role.
Type of resource this role applies to.
Array of permission slugs.
The created environment role.
listEnvironmentRoles Retrieve all environment roles.
const roleList = await workos . authorization . listEnvironmentRoles (); console . log ( roleList . data );
Array of environment roles.
getEnvironmentRole Retrieve an environment role by slug.
const role = await workos . authorization . getEnvironmentRole ( 'admin' );
The unique slug of the environment role.
The environment role object.
updateEnvironmentRole Update an environment role.
const role = await workos . authorization . updateEnvironmentRole ( 'admin' , { name: 'Super Administrator' , description: 'Updated description' , });
The unique slug of the environment role.
options
UpdateEnvironmentRoleOptions
required
The updated environment role.
setEnvironmentRolePermissions Set permissions for an environment role (replaces existing permissions).
const role = await workos . authorization . setEnvironmentRolePermissions ( 'admin' , { permissions: [ 'read' , 'write' , 'delete' , 'admin' ], });
The unique slug of the environment role.
options
SetEnvironmentRolePermissionsOptions
required
Array of permission slugs to set.
The updated environment role.
addEnvironmentRolePermission Add a single permission to an environment role.
const role = await workos . authorization . addEnvironmentRolePermission ( 'admin' , { permissionSlug: 'export' , });
The unique slug of the environment role.
options
AddEnvironmentRolePermissionOptions
required
The permission slug to add.
The updated environment role.
Organization Roles Organization roles are scoped to specific organizations.
createOrganizationRole Create a new organization role.
const role = await workos . authorization . createOrganizationRole ( 'org_123' , { slug: 'member' , name: 'Member' , description: 'Standard member access' , resourceTypeSlug: 'project' , permissions: [ 'read' , 'write' ], });
The ID of the organization.
options
CreateOrganizationRoleOptions
required
Unique identifier for the role.
Display name of the role.
Type of resource this role applies to.
Array of permission slugs.
The created organization role.
listOrganizationRoles Retrieve all roles for an organization.
const roleList = await workos . authorization . listOrganizationRoles ( 'org_123' ); console . log ( roleList . data );
The ID of the organization.
List of organization roles.
getOrganizationRole Retrieve an organization role by slug.
const role = await workos . authorization . getOrganizationRole ( 'org_123' , 'member' );
The ID of the organization.
The unique slug of the role.
The organization role object.
updateOrganizationRole Update an organization role.
const role = await workos . authorization . updateOrganizationRole ( 'org_123' , 'member' , { name: 'Team Member' , description: 'Updated description' , });
The ID of the organization.
The unique slug of the role.
options
UpdateOrganizationRoleOptions
required
The updated organization role.
deleteOrganizationRole Delete an organization role.
await workos . authorization . deleteOrganizationRole ( 'org_123' , 'member' );
The ID of the organization.
The unique slug of the role to delete.
setOrganizationRolePermissions Set permissions for an organization role.
const role = await workos . authorization . setOrganizationRolePermissions ( 'org_123' , 'member' , { permissions: [ 'read' , 'write' ], });
The ID of the organization.
The unique slug of the role.
options
SetOrganizationRolePermissionsOptions
required
Array of permission slugs to set.
The updated organization role.
addOrganizationRolePermission Add a permission to an organization role.
const role = await workos . authorization . addOrganizationRolePermission ( 'org_123' , 'member' , { permissionSlug: 'delete' , });
The ID of the organization.
The unique slug of the role.
options
AddOrganizationRolePermissionOptions
required
The permission slug to add.
The updated organization role.
removeOrganizationRolePermission Remove a permission from an organization role.
await workos . authorization . removeOrganizationRolePermission ( 'org_123' , 'member' , { permissionSlug: 'delete' , });
The ID of the organization.
The unique slug of the role.
options
RemoveOrganizationRolePermissionOptions
required
The permission slug to remove.
Permissions createPermission Create a new permission.
const permission = await workos . authorization . createPermission ({ slug: 'read' , name: 'Read' , description: 'Read access' , resourceTypeSlug: 'project' , });
options
CreatePermissionOptions
required
Unique identifier for the permission.
Display name of the permission.
Description of the permission.
Type of resource this permission applies to.
listPermissions Retrieve all permissions.
const permissionList = await workos . authorization . listPermissions ({ resourceTypeSlug: 'project' , }); console . log ( permissionList . data );
List of permissions with pagination metadata.
getPermission Retrieve a permission by slug.
const permission = await workos . authorization . getPermission ( 'read' );
The unique slug of the permission.
updatePermission Update a permission.
const permission = await workos . authorization . updatePermission ( 'read' , { name: 'Read Access' , description: 'Updated description' , });
The unique slug of the permission.
options
UpdatePermissionOptions
required
deletePermission Delete a permission.
await workos . authorization . deletePermission ( 'read' );
The unique slug of the permission to delete.
Resources createResource Create a new authorization resource.
const resource = await workos . authorization . createResource ({ externalId: 'project_123' , name: 'My Project' , description: 'A sample project' , resourceTypeSlug: 'project' , organizationId: 'org_123' , parentResourceId: 'parent_resource_123' , });
options
CreateAuthorizationResourceOptions
required
Your system’s identifier for this resource.
Display name of the resource.
Description of the resource.
ID of the parent resource (use this OR parentResourceExternalId).
External ID of the parent resource.
Type slug of the parent resource (required with parentResourceExternalId).
The created authorization resource.
getResource Retrieve a resource by ID.
const resource = await workos . authorization . getResource ( 'resource_123' );
The unique identifier of the resource.
The authorization resource object.
getResourceByExternalId Retrieve a resource by external ID.
const resource = await workos . authorization . getResourceByExternalId ({ organizationId: 'org_123' , resourceTypeSlug: 'project' , externalId: 'project_123' , });
options
GetAuthorizationResourceByExternalIdOptions
required
The ID of the organization.
Your system’s identifier for the resource.
The authorization resource object.
listResources Retrieve a list of resources.
const resourceList = await workos . authorization . listResources ({ organizationId: 'org_123' , resourceTypeSlug: 'project' , }); console . log ( resourceList . data );
options
ListAuthorizationResourcesOptions
Filter by organization ID.
resourceList
AuthorizationResourceList
List of authorization resources with pagination metadata.
updateResource Update a resource by ID.
const resource = await workos . authorization . updateResource ({ resourceId: 'resource_123' , name: 'Updated Project Name' , description: 'Updated description' , });
options
UpdateAuthorizationResourceOptions
required
The ID of the resource to update.
The updated authorization resource.
updateResourceByExternalId Update a resource by external ID.
const resource = await workos . authorization . updateResourceByExternalId ({ organizationId: 'org_123' , resourceTypeSlug: 'project' , externalId: 'project_123' , name: 'Updated Project Name' , });
options
UpdateAuthorizationResourceByExternalIdOptions
required
The ID of the organization.
Your system’s identifier for the resource.
The updated authorization resource.
deleteResource Delete a resource by ID.
await workos . authorization . deleteResource ({ resourceId: 'resource_123' , cascadeDelete: true , });
options
DeleteAuthorizationResourceOptions
required
The ID of the resource to delete.
Whether to delete child resources.
deleteResourceByExternalId Delete a resource by external ID.
await workos . authorization . deleteResourceByExternalId ({ organizationId: 'org_123' , resourceTypeSlug: 'project' , externalId: 'project_123' , cascadeDelete: true , });
options
DeleteAuthorizationResourceByExternalIdOptions
required
The ID of the organization.
Your system’s identifier for the resource.
Whether to delete child resources.
Authorization Checks Check if a user has a specific permission on a resource.
const result = await workos . authorization . check ({ organizationMembershipId: 'om_123' , permissionSlug: 'read' , resourceId: 'resource_123' , }); console . log ( result . authorized ); // true or false
options
AuthorizationCheckOptions
required
The organization membership ID to check.
The permission to check for.
The resource ID (use this OR externalId).
The resource external ID.
The resource type slug (required with resourceExternalId).
Whether the check passed.
Role Assignments assignRole Assign a role to a user for a specific resource.
const assignment = await workos . authorization . assignRole ({ organizationMembershipId: 'om_123' , roleSlug: 'admin' , resourceId: 'resource_123' , });
options
AssignRoleOptions
required
The organization membership ID.
The resource ID (use this OR externalId).
The resource external ID.
The resource type slug (required with resourceExternalId).
The created role assignment.
listRoleAssignments Retrieve role assignments for a user.
const assignments = await workos . authorization . listRoleAssignments ({ organizationMembershipId: 'om_123' , }); console . log ( assignments . data );
options
ListRoleAssignmentsOptions
required
The organization membership ID.
List of role assignments with pagination metadata.
removeRole Remove a role assignment.
await workos . authorization . removeRole ({ organizationMembershipId: 'om_123' , roleSlug: 'admin' , resourceId: 'resource_123' , });
options
RemoveRoleOptions
required
The organization membership ID.
The resource ID (use this OR externalId).
The resource external ID.
The resource type slug (required with resourceExternalId).
removeRoleAssignment Remove a role assignment by ID.
await workos . authorization . removeRoleAssignment ({ organizationMembershipId: 'om_123' , roleAssignmentId: 'ra_123' , });
options
RemoveRoleAssignmentOptions
required
The organization membership ID.
The role assignment ID to remove.
Resource Queries List resources a user has access to.
const resources = await workos . authorization . listResourcesForMembership ({ organizationMembershipId: 'om_123' , resourceTypeSlug: 'project' , }); console . log ( resources . data );
options
ListResourcesForMembershipOptions
required
The organization membership ID.
resources
AuthorizationResourceList
List of resources the user has access to.
listMembershipsForResource List users who have access to a resource.
const memberships = await workos . authorization . listMembershipsForResource ({ resourceId: 'resource_123' , }); console . log ( memberships . data );
options
ListMembershipsForResourceOptions
required
memberships
AuthorizationOrganizationMembershipList
List of organization memberships with access to the resource.
listMembershipsForResourceByExternalId List users who have access to a resource by external ID.
const memberships = await workos . authorization . listMembershipsForResourceByExternalId ({ organizationId: 'org_123' , resourceTypeSlug: 'project' , externalId: 'project_123' , }); console . log ( memberships . data );
options
ListMembershipsForResourceByExternalIdOptions
required
The resource external ID.
memberships
AuthorizationOrganizationMembershipList
List of organization memberships with access to the resource.