Skip to main content

If you are using our backend SDK that is lesser than the following versions, please visit the older documentation link here.

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("public", 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.

Multi Tenancy

Whilst roles and permissions are shared across apps, the association of roles to users is on a per tenant level. If using our SDK functions to add a role to a user, you can also pass in a tenantId to the function which will tell SuperTokens to add the role for that user for that tenant.

In the code examples above, we pass in the "public" tenantId, 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 teannt, and that user ID doesn't actually belong to that tenant, then the operation will still succeed.

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.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

If you are using our multi tenancy feature, it is important to note that in the code snippets above, we only remove the user's role for the tenant that they used to login into (which is what's 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 (which you can fetch from the user object associated with the userId).

Get all roles for a user#

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

tip

You can also view all the roles that are assigned to a user from the user management dashboard on the user details page for that particular user. To know more about how to manage your user roles and permissions from user management dashboard see this page

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, we pass in the "public" tenantId, 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).

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("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, we pass in the "public" tenantId, which is the default tenantId for users. This will return 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.

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:

Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI