Skip to main content

Managing permissions for a role#

With the UserRoles recipe you can:

  • Add permissions to a role
  • Remove permissions from a role
  • Get a list of all permissions assigned to a role
  • Get a list of all roles that have a specific permission

Add permissions#

The createNewRoleOrAddPermissions can be used to add new permissions to a role. This function only adds missing permissions to a role and will not have any effect on permissions that are already assigned to a role.

import UserRoles from "supertokens-node/recipe/userroles";

async function addPermissionForRole() {
    // Add the "write" permission to the "user" role
    await UserRoles.createNewRoleOrAddPermissions("user", ["write"]);
}
Multi Tenancy

In a multi tenant setup, roles and permissions are shared across all tenants. This means that you can create a role and add permissions to it once, and reuse that role across any tenant in your app.

Remove permissions#

You can remove one or more permissions from a role, the role must be created before using this function.

import UserRoles from "supertokens-node/recipe/userroles";

async function removePermissionFromRole() {
    // Remove the "write" permission to the "user" role
    const response = await UserRoles.removePermissionsFromRole("user", ["write"]);

    if (response.status === "UNKNOWN_ROLE_ERROR") {
        // No such role exists
    }
}

Get all permissions for a role#

Get a list of all permissions assigned to a role

import UserRoles from "supertokens-node/recipe/userroles";

async function getPermissionsForRole() {
    const response = await UserRoles.getPermissionsForRole("user");

    if (response.status === "UNKNOWN_ROLE_ERROR") {
        // No such role exists
        return;
    }

    const permissions: string[] = response.permissions;
}

Get all roles that have a permission#

Get a list of all roles that have been assigned a specific permission

import UserRoles from "supertokens-node/recipe/userroles";

async function getRolesWithPermission() {
    const response = await UserRoles.getRolesThatHavePermission("write");
    const roles: string[] = response.roles;
}
Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI