Descope allows you to assign roles and permissions to the application's end user. Users with Descope admin
privileges can define roles and permissions in the Descope console.
Permissions and roles are represented as strings in Descope. Your application must do the interpretation and
enforcement of the roles and permissions.
Permissions are used within roles. Within the Permissions tab
of the console, under Authorization you can create and manage your permissions. Clicking the + Permission Button
at the top right allows you to create the permission. You can also click the three dots to the right of the permission
to delete the permission or change it's description.
Within the Roles tab of the console, under Authorization you can
create and manage your roles. Clicking the + Role Button at the top right allows you to create the role. You
can also click the three dots to the right of the role to delete the role, change it's description, or add
permissions to the role.
Each user that is created in your application (during sign-up) can be assigned roles and permissions. The user
can get more than one role and will include the role's associated permissions. The assignment of roles and
permissions can be done manually (not recommended) using the console, using the management SDK (sample
code below), or can be automatically mapped if you use SSO (SAML) as the authentication method for your application.
You can edit and add roles to users within the Users page.
Roles have two main types, Tenant and Project. Every role that's configured in a specific project, will either be specific to a Tenant or the entire Project, depending on this type.
When you create roles you have the option to assign them to a specific tenant with the respective Tenant ID, shown in the docs below.
If you are using tenants for user management, then the same user can be assigned different roles and permissions for each tenant (if you so desire).
These can be automatically assigned using SSO Configuration too. The Tenant Management section covers the steps to configure roles mapping using SAML.
After successful end-user authentication, the roles and permissions are delivered to your application as part of the JWT token. Below is a sample JWT
token that contains roles and permissions with a user logged into a tenant.
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
This Descope SDK 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.
This Descope SDK 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.")}
This Descope SDK 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.
This Descope SDK 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 byconst tenant_ids = ["Tenant ID"]// role_names (List[str]): Only return matching roles to the given namesconst role_names = ["Role name"]// role_name_like (str): Return roles that contain the given string ignoring caseconst role_name_like = "string in role"// permission_names (List[str]): Only return roles that have the given permissionsconst 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)}
This Descope SDK 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 tenantconst 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.")}
This Descope SDK 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 tenantconst 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.")}
This Descope SDK 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 tenantconst 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.")}