Skip to main content

Managing roles and users

With the UserRoles recipe you can:

  • Assign roles to users and their sessions
  • Remove roles from users and their sessions
  • Get a list of all roles assigned to a specific user
  • Get a list of all users that are assigned a specific role

Assign roles to a user and their session#

You can assign roles to users before hand or immediately after they sign up. The role must be created before you can assign it.

import UserRoles from "supertokens-node/recipe/userroles";
async function addRoleToUser(userId: string) {    const response = await UserRoles.addRoleToUser(userId, "user");
    if (response.status === "UNKNOWN_ROLE_ERROR") {        // No such role exists        return;    }
    if (response.didUserAlreadyHaveRole === true) {        // The user already had the role    }}

Normally, you would do the above in the sign up function override. This way, SuperTokens would automatically add the roles & permissions of the user to their session.

However, in case you associate the roles to a user after the session has already been created, then you can also manually add the roles and permissions to a session using in the following way:

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)}
important

The session variable in the code snippet above refers to the session object that's the result of calling the verifySession or getSession function.

Remove role from a user and their sessions#

You can remove roles from a user, the role you provide will be removed only if the user was assigned 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.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);    }}

Get all roles for a user#

You can get a list of all roles that were assigned to a specific user.

import UserRoles from "supertokens-node/recipe/userroles";
async function getRolesForUser(userId: string) {    const response = await UserRoles.getRolesForUser(userId);    const roles: string[] = response.roles;}

Get all users that have a role#

You can get a list of all users that were assigned a specific role, the getRolesForUser returns a list of user ids.

import UserRoles from "supertokens-node/recipe/userroles";
async function getUsersThatHaveRole(role: string) {    const response = await UserRoles.getUsersThatHaveRole(role);
    if (response.status === "UNKNOWN_ROLE_ERROR") {        // No such role exists        return;    }
    const users: string[] = response.users;}
Which frontend SDK do you use?
supertokens-web-js / mobile
supertokens-auth-react