Role management actions

Overview

SuperTokens exposes a set of functions and APIs that you can use to have fine-grained control over roles and permissions. Actions like listing roles, creating permissions, or checking which roles you assign are available through different SDK calls.

Before you start

info

You can also perform most of the actions outlined on this page from the user management dashboard. To know more about how to use it check the documentation

Create a role

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

async function createRole() {
    const response = await UserRoles.createNewRoleOrAddPermissions("user", ["read"]);

    if (response.createdNewRole === false) {
        // The role already exists
    }
}

List roles

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

async function getAllRoles() {
    const roles: string[] = (await UserRoles.getAllRoles()).roles;
}

Delete a role

You can delete any role you have created, if the role you are trying to delete does not exist then this has no effect.

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

async function deleteRole() {
    // Delete the user role
    const response = await UserRoles.deleteRole("user");

    if (!response.didRoleExist) {
        // There was no such role
    }
}

Add permissions

The SDK function only adds missing permissions and does 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 share 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

To remove one or more permissions from a role, first create the role before you use 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 permissions by 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 roles by permission

Get a list of all the roles 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;
}

Assign roles to a user

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

async function addRoleToUser(userId: string) {
    const response = await UserRoles.addRoleToUser("public", userId, "user");

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

    if (response.didUserAlreadyHaveRole === true) {
        // The user already had the role
    }
}

Assign roles to a session

import {UserRoleClaim, PermissionClaim} from "supertokens-node/recipe/userroles";
import {SessionContainer} from "supertokens-node/recipe/session"

async function addRolesAndPermissionsToSession(session: SessionContainer) {
    // we add the user's roles to the user's session
	await session.fetchAndSetClaim(UserRoleClaim)

	// we add the permissions of a user to the user's session
	await session.fetchAndSetClaim(PermissionClaim)
}

Multi Tenancy

Whilst roles and permissions share across apps, the association of roles to users is on a per-tenant level. If using SDK functions to add a role to a user, you can also pass in a tenantId to the function. This tells SuperTokens to add the role for that user for that tenant.

In the code examples above, the "public" tenantId appears, which is the default tenantId for users. You can fetch the user's tenantId from their current session, or from their user object (which you can fetch using their userId).

Note that if you associate a role to a user ID for a tenant, and that user ID doesn't actually belong to that tenant, then the operation still succeeds.

Remove role from a user and their sessions

You can remove roles from a user. The system removes the role you provide only if the user previously had that role.

import UserRoles from "supertokens-node/recipe/userroles";
import { SessionContainer } from "supertokens-node/recipe/session"

async function removeRoleFromUserAndTheirSession(session: SessionContainer) {
    const response = await UserRoles.removeUserRole(session.getTenantId(), session.getUserId(), "user");

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

    if (response.didUserHaveRole === false) {
        // The user was never assigned the role
    } else {
        // We also want to update the session of this user to reflect this change.
        await session.fetchAndSetClaim(UserRoles.UserRoleClaim);
        await session.fetchAndSetClaim(UserRoles.PermissionClaim);
    }
}

Multi Tenancy

When using the multi-tenancy feature, in the previous snippets, only the user's role for the tenant they used to log in gets removed. That's the one stored in the session.

You can pass in another tenant ID if you like, or call the function above for all the tenants that the user belongs to.

List the roles of a user

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

async function getRolesForUser(userId: string) {
    const response = await UserRoles.getRolesForUser("public", userId);
    const roles: string[] = response.roles;
}

Multi Tenancy

In the code examples above, the "public" tenantId appears, which is the default tenantId for users. You can fetch the user's tenantId from their current session, or from their user object (which you can fetch using their userId).

List the users of a role

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

async function getUsersThatHaveRole(role: string) {
    const response = await UserRoles.getUsersThatHaveRole("public", role);

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

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

Multi Tenancy

In the code examples above, the "public" tenantId appears, which is the default tenantId for users. This returns the list of users that have that role in the "public" tenant.

You can also pass in a different tenant ID, or call the function in a loop with all the tenants that exist in your app.

See also

Claim validationProtect backend routesProtect frontend routes