Authorization/Role-Based Access Control (RBAC)

RBAC with SDKs

Descope's Role-Based Access Control (RBAC) system provides a flexible and powerful way to manage user permissions in your applications. You can use these SDK functions to implement RBAC in your application.

Install SDK

Terminal
npm i --save @descope/node-sdk

Import and initialize Management SDK

import DescopeClient from '@descope/node-sdk';
 
const managementKey = "xxxx"
 
try{
    //  baseUrl="<URL>" // When initializing the Descope clientyou can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__', managementKey: managementKey });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}
 
// Note that you can handle async operation failures and capture specific errors to customize errors.
//     An example can be found here: https://github.com/descope/node-sdk?tab=readme-ov-file#error-handling

Load All Permissions

This function allows administrators to return all details for permissions configured within the Descope instance. The response includes an array of permissions and the details of each permission.

const resp = await descopeClient.management.permission.loadAll()
if (!resp.ok) {
  console.log("Failed to load permissions.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully loaded permissions.")
  console.log(resp.data)
}

Create a Permission

This function allows administrators to create a new permission.

// Args:
// 		name (str): permission name.
const name = "Test Permission"
// 		description (str): Optional description to briefly explain what this permission allows.
const description = "My description"
 
const resp = await descopeClient.management.permission.create(name, description)
if (!resp.ok) {
  console.log("Failed to create permission.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully created permission.")
}

Update a Permission

This function allows administrators to update an existing permission with the given various fields. It is important to note that parameters are used as overrides to the existing permission; empty fields will override populated fields.

// Args:
// 		name (str): permission name.
const name = "Test Permission"
// 		newName (str): permission updated name.
const newName = "Updated Test Permission"
// 		description (str): Optional description to briefly explain what this permission allows.
const description = "My updated description"
 
const resp = await descopeClient.management.permission.update(name, newName, description)
if (!resp.ok) {
  console.log("Failed to update permission.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully updated permission.")
}

Delete a Permission

This function allows administrators to delete an existing permission. It is important to note that this action is irreversible.

// Args:
// 		name (str): The name of the permission to be deleted.
const name = "Updated Test Permission"
 
const resp = await descopeClient.management.permission.delete(name)
if (!resp.ok) {
  console.log("Failed to delete permission.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully deleted permission.")
}

Load All Roles

This function allows administrators to return all details for roles configured within the Descope instance. The response includes an array of roles and the details of each role.

const resp = await descopeClient.management.role.loadAll()
if (!resp.ok) {
  console.log("Failed to load roles.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully loaded roles.")
  console.log(resp.data)
}

Search for Roles

This function allows administrators to return specific roles configured within the Descope instance using several parameters. The response includes an array of roles and the details of each role.

// Args:
//    tenant_ids (List[str]): List of tenant ids to filter by
const tenant_ids = ["Tenant ID"]
//    role_names (List[str]): Only return matching roles to the given names
const role_names = ["Role name"]
//    role_name_like (str): Return roles that contain the given string ignoring case
const role_name_like = "string in role"
//    permission_names (List[str]): Only return roles that have the given permissions
const permission_names = ["TestPermission"]
 
const resp = await descopeClient.management.role.search(tenant_ids, role_names, role_name_like, permission_names)
if (!resp.ok) {
  console.log("Failed to Search for roles.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully searched for roles.")
  console.log(resp.data)
}

Create a Role

This function allows administrators to create a new role.

// Args:
//    name (str): role name.
const name = "My Test Role"
// description (str): Optional description to briefly explain what this role allows.
const description = "My Role Description"
// permissionNames (List[str]): Optional list of names of permissions this role grants.
const permissionNames = ["TestPermission"]
//    tenantId (str): Optional Tenant ID to assign new role to specific tenant
const tenantId = "Tenant ID"
 
const resp = await descopeClient.management.role.create(name, description, permissionNames, tenantId)
if (!resp.ok) {
  console.log("Failed to create role.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully created role.")
}

Update a Role

This function allows administrators to update an existing role with the given various fields. It is important to note that parameters are used as overrides to the existing role; empty fields will override populated fields.

// Args:
//    name (str): role name.
const name = "My Test Role"
//    newName (str): role updated name.
const newName = "My Updated Test Role"
//    description (str): Optional description to briefly explain what this role allows.
const description = "My Updated Role Description"
//    permissionNames (List[str]): Optional list of names of permissions this role grants.
const permissionNames = ["TestPermission", "TestPermission2"]
//    tenantId (str): Optional Tenant ID to assign new role to specific tenant
const tenantId = "Tenant ID"
 
const resp = await descopeClient.management.role.update(name, newName, description, permissionNames, tenantId)
if (!resp.ok) {
  console.log("Failed to update role.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully updated role.")
}

Delete a Role

This function allows administrators to delete an existing role. It is important to note that this action is irreversible.

// Args:
//    name (str): The name of the role to be deleted.
const name = "My Updated Test Role"
//    tenantId (str): Optional Tenant ID to assign new role to specific tenant
const tenantId = "Tenant ID"
 
const resp = await descopeClient.management.role.delete(name, tenantId)
if (!resp.ok) {
  console.log("Failed to delete role.")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully deleted role.")
}
Was this helpful?

Role-Based Access Control (RBAC)

Learn how to assign roles and permissions to the application's end users and configure user roles with Descope.

Next

B2B Example

On this page