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 (see end of this page). 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 (see end of this page). 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 API to override for adding roles post sign up?#

Follow the links below to see documentation on post sign up action for the recipe you use:

Which frontend SDK do you use?
supertokens-web-js / mobile
supertokens-auth-react