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.

NodeJS
GoLang
Python
cURL

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

import (
    "github.com/supertokens/supertokens-golang/recipe/userroles"
)

func addRoleToUser(userId string) {
    response, err := userroles.AddRoleToUser(userId, "user", nil)
    if err != nil {
        // TODO: Handle error
        return
    }

    if response.UnknownRoleError != nil {
        // No such role exists
        return
    }

    if response.OK.DidUserAlreadyHaveRole {
        // The user already had the role
    }
}

Asyncio
Syncio

from supertokens_python.recipe.userroles.asyncio import add_role_to_user
from supertokens_python.recipe.userroles.interfaces import UnknownRoleError


async def add_role_to_user_func(user_id: str, role: str):
    role = "user"
    res = await add_role_to_user(user_id, role)
    if isinstance(res, UnknownRoleError):
        # No such role exists
        return

    if res.did_user_already_have_role:
        # User already had this role
        pass

from supertokens_python.recipe.userroles.syncio import add_role_to_user
from supertokens_python.recipe.userroles.interfaces import UnknownRoleError


def add_role_to_user_func(user_id: str, role: str):
    role = "user"
    res = add_role_to_user(user_id, role)
    if isinstance(res, UnknownRoleError):
        # No such role exists
        return

    if res.did_user_already_have_role:
        # User already had this role
        pass

curl --location --request PUT '/recipe/user/role' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
  "userId": "fa7a0841-b533-4478-95533-0fde890c3483",
  "role": "user"
}'

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:

NodeJS
GoLang
Python

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

import (
    "github.com/supertokens/supertokens-golang/recipe/session/sessmodels"
    "github.com/supertokens/supertokens-golang/recipe/userroles/userrolesclaims"
)

func addRolesAndPermissionsToSession(session sessmodels.SessionContainer) error {
    // we add the user's roles to the user's session
    err := session.FetchAndSetClaim(userrolesclaims.UserRoleClaim)
    if err != nil {
        return err
    }

    // we add the user's permissions to the user's session
    err = session.FetchAndSetClaim(userrolesclaims.PermissionClaim)
    if err != nil {
        return err
    }

    return nil
}

Asyncio
Syncio

from supertokens_python.recipe.session import SessionContainer
from supertokens_python.recipe.userroles import UserRoleClaim, PermissionClaim


async def add_roles_and_permissions_to_session(session: SessionContainer):
    # we add the user's roles to the user's session
    await session.fetch_and_set_claim(UserRoleClaim)

    # we add the user's permissions to the user's session
    await session.fetch_and_set_claim(PermissionClaim)

from supertokens_python.recipe.session import SessionContainer
from supertokens_python.recipe.userroles import UserRoleClaim, PermissionClaim


def add_roles_and_permissions_to_session(session: SessionContainer):
    # we add the user's roles to the user's session
    session.sync_fetch_and_set_claim(UserRoleClaim)
    
    # we add the user's permissions to the user's session
    session.sync_fetch_and_set_claim(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.

NodeJS
GoLang
Python
cURL

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

import (
    "github.com/supertokens/supertokens-golang/recipe/session/sessmodels"
    "github.com/supertokens/supertokens-golang/recipe/userroles"
    "github.com/supertokens/supertokens-golang/recipe/userroles/userrolesclaims"
)

func removeRoleFromUserAndTheirSession(session sessmodels.SessionContainer) {
    response, err := userroles.RemoveUserRole(session.GetUserID(), "user", nil)
    if err != nil {
        // TODO: Handle error
        return
    }

    if response.UnknownRoleError != nil {
        // No such role exists
        return
    }

    if response.OK.DidUserHaveRole == false {
        // The user was never assigned the role
    } else {
        // We also want to update the session of this user to reflect this change.
        session.FetchAndSetClaim(userrolesclaims.UserRoleClaim)
        session.FetchAndSetClaim(userrolesclaims.PermissionClaim)
    }
}

Asyncio
Syncio

from supertokens_python.recipe.userroles.asyncio import remove_user_role
from supertokens_python.recipe.userroles.interfaces import UnknownRoleError
from supertokens_python.recipe.userroles import UserRoleClaim, PermissionClaim
from supertokens_python.recipe.session import SessionContainer

async def remove_role_from_user_and_their_session(session: SessionContainer):
    res = await remove_user_role(session.get_user_id(), "user")
    if isinstance(res, UnknownRoleError):
        # No such role exists
        return

    if res.did_user_have_role == False:
        # The user was never assigned the role
        pass
    else:
        # We also want to update the session of this user to reflect this change.
        await session.fetch_and_set_claim(UserRoleClaim)
        await session.fetch_and_set_claim(PermissionClaim)

from supertokens_python.recipe.userroles.syncio import remove_user_role
from supertokens_python.recipe.userroles.interfaces import UnknownRoleError
from supertokens_python.recipe.userroles import UserRoleClaim, PermissionClaim
from supertokens_python.recipe.session import SessionContainer

def remove_role_from_user_and_their_session(session: SessionContainer):
    res = remove_user_role(session.get_user_id(), "user")
    if isinstance(res, UnknownRoleError):
        # No such role exists
        return

    if res.did_user_have_role == False:
        # The user was never assigned the role
        pass
    else:
        # We also want to update the session of this user to reflect this change.
        session.sync_fetch_and_set_claim(UserRoleClaim)
        session.sync_fetch_and_set_claim(PermissionClaim)

curl --location --request POST '/recipe/user/role/remove' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
  "userId": "fa7a0841-b533-4478-95533-0fde890c3483",
  "role": "user"
}'

Get all roles for a user#

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

NodeJS
GoLang
Python
cURL

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

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

import (
    "github.com/supertokens/supertokens-golang/recipe/userroles"
)

func getRolesForUser(userId string) {
    response, err := userroles.GetRolesForUser(userId, nil)
    if err != nil {
        // TODO: Handle error
        return
    }
    _ = response.OK.Roles
}

Asyncio
Syncio

from supertokens_python.recipe.userroles.asyncio import get_roles_for_user

async def get_roles_for_user_func(user_id: str):
    _ = (await get_roles_for_user(user_id)).roles

from supertokens_python.recipe.userroles.syncio import get_roles_for_user

def get_roles_for_user_func(user_id: str):
    _ = get_roles_for_user(user_id).roles

curl --location --request GET '/recipe/user/roles?userId=fa7a0841-b533-4478-95533-0fde890c3483' \
--header 'api-key: '

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.

NodeJS
GoLang
Python
cURL

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;
}

import (
    "github.com/supertokens/supertokens-golang/recipe/userroles"
)

func getUsersThatHaveRole(role string) {
    response, err := userroles.GetUsersThatHaveRole(role, nil)
    if err != nil {
        // TODO: Handle error
        return
    }

    if response.UnknownRoleError != nil {
        // No such role exists
        return
    }

    _ = response.OK.Users
}

Asyncio
Syncio

from supertokens_python.recipe.userroles.asyncio import get_users_that_have_role
from supertokens_python.recipe.userroles.interfaces import UnknownRoleError

async def get_users_that_have_role_func(role: str):
    res = await get_users_that_have_role(role)
    if isinstance(res, UnknownRoleError):
        # No such role exists
        return

    _ = res.users

from supertokens_python.recipe.userroles.syncio import get_users_that_have_role
from supertokens_python.recipe.userroles.interfaces import UnknownRoleError

def get_users_that_have_role_func(role: str):
    res = get_users_that_have_role(role)
    if isinstance(res, UnknownRoleError):
        # No such role exists
        return

    _ = res.users

curl --location --request GET '/recipe/role/users?role=user' \
--header 'api-key: '

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: