Role management actions

Discover how to perform common actions that can be use to manage roles and permissions.

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

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

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

func createRole() {
	resp, err := userroles.CreateNewRoleOrAddPermissions("user", []string{
		"read",
	}, nil)

	if err != nil {
		// TODO: Handle error
		return
	}
	if resp.OK.CreatedNewRole == false {
		// The role already exists
	}
}

from supertokens_python.recipe.userroles.asyncio import create_new_role_or_add_permissions

async def create_role():
    res = await create_new_role_or_add_permissions("user", ["read"])
    if not res.created_new_role:
        # The role already existed
        pass

from supertokens_python.recipe.userroles.syncio import create_new_role_or_add_permissions

def create_role():
    res = create_new_role_or_add_permissions("user", ["read"])
    if not res.created_new_role:
        # The role already existed
        pass

curl --location --request PUT '<CORE_API_ENDPOINT>/recipe/role' \
--header 'api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
  "role": "user",
  "permissions": [
    "read"
  ]
}'

List roles

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

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

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

func getAllRoles() {
	response, err := userroles.GetAllRoles(nil)
	if err != nil {
		// TODO: Handle error
		return
	}
	_ = response.OK.Roles
}

from supertokens_python.recipe.userroles.asyncio import get_all_roles

async def create_role():
	_ = (await get_all_roles()).roles

from supertokens_python.recipe.userroles.syncio import get_all_roles

def create_role():
	_ = get_all_roles().roles

curl --location --request GET 'http://localhost:3567/recipe/roles' \
--header 'api-key: <YOUR_API_KEY>'

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

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

func deleteRole() {
	// Delete the user role
	response, err := userroles.DeleteRole("user", nil)
	if err != nil {
		// TODO: Handle error
		return
	}

	if response.OK.DidRoleExist == false {
		// There was no such role
	}
}

from supertokens_python.recipe.userroles.asyncio import delete_role

async def delete_role_function():
    res = await delete_role("user")
    if res.did_role_exist:
        # The role actually existed
        pass

from supertokens_python.recipe.userroles.syncio import delete_role

def delete_role_function():
    res = delete_role("user")
    if res.did_role_exist:
        # The role actually existed
        pass

curl --location --request POST 'http://localhost:3567/recipe/role/remove' \
--header 'api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
  "role": "admin"
}'

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

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

func addPermissionForRole() {
	// Add the write permission to the user role
	_, err := userroles.CreateNewRoleOrAddPermissions("user", []string{"write"}, nil)
	if err != nil {
		// TODO: Handle error
		return
	}
}

from supertokens_python.recipe.userroles.asyncio import create_new_role_or_add_permissions


async def add_permission_for_role():
	await create_new_role_or_add_permissions("user", ["write"])

from supertokens_python.recipe.userroles.syncio import create_new_role_or_add_permissions


def add_permission_for_role():
	create_new_role_or_add_permissions("user", ["write"])

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

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

func removePermissionFromRole() {
	// Remove the write permission to the user role
	response, err := userroles.RemovePermissionsFromRole("user", []string{"write"}, nil)
	if err != nil {
		// TODO: Handle error
		return
	}

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

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

async def remove_permission_from_role_func():
	res = await remove_permissions_from_role("user", ["write"])
	if isinstance(res, UnknownRoleError):
		# No such role exists
		pass

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

def remove_permission_from_role_func():
	res = remove_permissions_from_role("user", ["write"])
	if isinstance(res, UnknownRoleError):
		# No such role exists
		pass

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

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

func getPermissionsForRole() {
	// const response = await UserRoles.getPermissionsForRole("user");
	response, err := userroles.GetPermissionsForRole("user", nil)
	if err != nil {
		// TODO: Handle error
		return
	}

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

	_ = response.OK.Permissions
}

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

async def remove_permission_from_role():
	res = await get_permissions_for_role("user")
	if isinstance(res, UnknownRoleError):
		# No such role exists
		return

	_ = res.permissions

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

def remove_permission_from_role():
	res = get_permissions_for_role("user")
	if isinstance(res, UnknownRoleError):
		# No such role exists
		return

	_ = res.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;
}

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

func getRolesWithPermission() {
	response, err := userroles.GetRolesThatHavePermission("write", nil)
	if err != nil {
		// TODO: Handle error
		return
	}
	_ = response.OK.Roles
}

from supertokens_python.recipe.userroles.asyncio import get_roles_that_have_permission


async def get_roles_with_permission():
	res = await get_roles_that_have_permission("write")
	_ = res.roles

from supertokens_python.recipe.userroles.syncio import get_roles_that_have_permission


def get_roles_with_permission():
	res = get_roles_that_have_permission("write")
	_ = res.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
  }
}

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

func addRoleToUser(userId string) {
	response, err := userroles.AddRoleToUser("public", 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
	}
}

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 = "user"
	res = await add_role_to_user("public", 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 = "user"
	res = add_role_to_user("public", 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 'http://localhost:3567/recipe/user/role' \
--header 'api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
  "userId": "fa7a0841-b533-4478-95533-0fde890c3483",
  "role": "user"
}'

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

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
}

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)

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

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.GetTenantId(), 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)
	}
}

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_tenant_id(), 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_tenant_id(), 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 'http://localhost:3567/recipe/user/role/remove' \
--header 'api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
  "userId": "fa7a0841-b533-4478-95533-0fde890c3483",
  "role": "user"
}'

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

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

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

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

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

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

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

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

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

	_ = response.OK.Users
}

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("public", 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("public", role)
	if isinstance(res, UnknownRoleError):
		# No such role exists
		return

	_ = res.users

curl --location --request GET 'http://localhost:3567/recipe/role/users?role=user' \
--header 'api-key: <YOUR_API_KEY>'