Roles
Define and assign organization roles
Use the role client to define organization roles and list role assignments.
Create roles and permissions for authorization after you have organizations and users.
createRole
Section titled “createRole”#asynccreateRole
Creates a new environment-level role with specified permissions.
Role creation object containing:
The created role with metadata
const response = await scalekit.role.createRole({ name: 'content_editor', displayName: 'Content Editor', description: 'Can create and edit content', permissions: ['content:read', 'content:write', 'content:edit']});getRole
Section titled “getRole”#asyncgetRole
Retrieves complete information for a specific environment role.
Unique role identifier (alphanumeric with underscores, hyphens allowed).
Role details including permissions and inheritance
const response = await scalekit.role.getRole('content_editor');console.log('Role:', response.role.displayName);console.log('Permissions:', response.role.permissions);listRoles
Section titled “listRoles”#asynclistRoles
Lists all environment-level roles available in your Scalekit environment.
Array of all roles with their metadata
const response = await scalekit.role.listRoles();response.roles.forEach(role => { console.log(`${role.displayName}: ${role.permissions.length} permissions`);});updateRole
Section titled “updateRole”#asyncupdateRole
Updates an existing environment role’s properties and permissions.
Role to update
Updated role properties
Updated role details
await scalekit.role.updateRole('content_editor', { displayName: 'Content Editor (Updated)', permissions: ['content:read', 'content:write', 'content:edit', 'content:review']});deleteRole
Section titled “deleteRole”#asyncdeleteRole
Deletes an environment role and reassigns its users to another role.
Role to delete
Optional. Target role for user migration
Empty response on success
await scalekit.role.deleteRole('old_role', 'new_role');deleteRoleBase
Section titled “deleteRoleBase”#asyncdeleteRoleBase
Removes an environment role’s inheritance relationship, eliminating inherited permissions from its base role.
Role to remove inheritance from
Empty response on success
getRoleUsersCount
Section titled “getRoleUsersCount”#asyncgetRoleUsersCount
Gets the number of users assigned to an environment role.
Role to count users for
Total user count (direct and inherited)
const response = await scalekit.role.getRoleUsersCount('admin');console.log(`${response.count} users have admin role`);createOrganizationRole
Section titled “createOrganizationRole”#asynccreateOrganizationRole
Creates a new organization-specific role with custom permissions.
Organization identifier (format: “org_…”)
Role configuration containing:
Created organization role
await scalekit.role.createOrganizationRole('org_123456', { name: 'department_lead', displayName: 'Department Lead', description: 'Manages department members', permissions: ['dept:members:read', 'dept:members:invite']});getOrganizationRole
Section titled “getOrganizationRole”#asyncgetOrganizationRole
Retrieves details for a specific organization role.
Organization identifier
Role name to retrieve
Organization role details
const response = await scalekit.role.getOrganizationRole( 'org_123456', 'department_lead');
console.log('Permissions:', response.role.permissions);listOrganizationRoles
Section titled “listOrganizationRoles”#asynclistOrganizationRoles
Lists all roles available to an organization (environment + organization-specific).
Organization identifier
Array of available roles
const response = await scalekit.role.listOrganizationRoles('org_123456');response.roles.forEach(role => { console.log(`${role.displayName} (${role.scope})`);});updateOrganizationRole
Section titled “updateOrganizationRole”#asyncupdateOrganizationRole
Updates an organization role’s properties and permissions.
Organization identifier
Role to update
Updated role properties
Updated role
await scalekit.role.updateOrganizationRole('org_123456', 'department_lead', { permissions: ['dept:members:read', 'dept:members:invite', 'dept:members:remove']});deleteOrganizationRole
Section titled “deleteOrganizationRole”#asyncdeleteOrganizationRole
Deletes an organization role and reassigns its users.
Organization identifier
Role to delete
Optional. Target role for user migration
Empty response on success
await scalekit.role.deleteOrganizationRole( 'org_123456', 'old_role', 'new_role');getOrganizationRoleUsersCount
Section titled “getOrganizationRoleUsersCount”#asyncgetOrganizationRoleUsersCount
Gets the number of users assigned to an organization role.
Organization identifier
Role to count users for
User count
const response = await scalekit.role.getOrganizationRoleUsersCount( 'org_123456', 'admin');
console.log(`${response.count} admins in this organization`);updateDefaultRoles
Section titled “updateDefaultRoles”#asyncupdateDefaultRoles
Sets the default creator and/or member roles for the environment.
Optional fields: defaultCreatorRole, defaultMemberRole.
Updated default roles configuration
listDependentRoles
Section titled “listDependentRoles”#asynclistDependentRoles
Lists all roles that extend (depend on) the specified role.
Role to find dependents for
Array of roles that depend on the given role
updateDefaultOrganizationRoles
Section titled “updateDefaultOrganizationRoles”#asyncupdateDefaultOrganizationRoles
Sets the default role automatically assigned to new organization members.
Organization identifier
Role name to assign by default
Updated configuration
await scalekit.role.updateDefaultOrganizationRoles('org_123456', 'member');deleteOrganizationRoleBase
Section titled “deleteOrganizationRoleBase”#asyncdeleteOrganizationRoleBase
Removes a role’s inheritance relationship, eliminating inherited permissions from base role.
Organization identifier
Role to remove inheritance from
Empty response on success
await scalekit.role.deleteOrganizationRoleBase('org_123456', 'custom_role');