b2c_tooling_sdk.operations.bm_roles

Business Manager role operations for B2C Commerce instances.

Mirrors src/operations/bm-roles/index.ts. This module provides functions for managing instance-level access roles on B2C Commerce instances via the OCAPI Data API. These are distinct from Account Manager roles managed via b2c_tooling_sdk.operations.roles.

Core Role Functions

• list_bm_roles -- List all access roles on an instance
• get_bm_role -- Get role details with optional expansion
• create_bm_role -- Create a new access role
• delete_bm_role -- Delete an access role

User Assignment

• grant_bm_role -- Assign a user to a role
• revoke_bm_role -- Unassign a user from a role

Permissions

• get_bm_role_permissions -- Get permissions for a role
• set_bm_role_permissions -- Replace all permissions for a role

Usage

from b2c_tooling_sdk.operations.bm_roles import list_bm_roles, grant_bm_role, get_bm_role_permissions
from b2c_tooling_sdk.config import resolve_config

config = resolve_config()
instance = config.create_b2c_instance()

# List all roles
roles = await list_bm_roles(instance)

# Grant a role to a user
await grant_bm_role(instance, "Administrator", "user@example.com")

# Get permissions for a role
permissions = await get_bm_role_permissions(instance, "Administrator")

Authentication

BM role operations require OAuth authentication with appropriate OCAPI permissions for the /roles resource.

SCAPI/OCAPI dual backend

create_roles_backend resolves a RolesBackend (SCAPI-backed by default, with OCAPI fallback) for callers that want a single interface instead of the module-level OCAPI-only functions above.

Classes

CreateRoleInput

class CreateRoleInput

Options for RolesBackend.create_role.

Fields

Name	Type	Default
description	str | None	None

GetBmRoleOptions

class GetBmRoleOptions

Options for getting a BM role.

Fields

Name	Type	Default
expand	Sequence[str] | None	None

ListBmRolesOptions

class ListBmRolesOptions

Options for listing BM roles.

Fields

Name	Type	Default
start	int | None	None
count	int | None	None

ListRolesOptions

class ListRolesOptions

Options for RolesBackend.list_roles.

Fields

Name	Type	Default
start	int | None	None
count	int | None	None
expand	list[RoleExpand] | None	None

ListRolesResult

class ListRolesResult

Paginated result of RolesBackend.list_roles.

Fields

Name	Type	Default
total	int
start	int
count	int
hits	list[RoleInfo]	field(default_factory=list)

OcapiRolesBackend

class OcapiRolesBackend

Business Manager roles backend implemented against the OCAPI Data API.

Fields

Name	Type
name	Literal['ocapi']

RoleInfo

class RoleInfo

Normalized role summary, shared by both backends.

Fields

Name	Type	Default
id	str
description	str | None	None
user_count	int | None	None
user_manager	bool | None	None
permissions	RolePermissionsInfo | None	None
raw	Any	None

RolesBackend

class RolesBackend(BackendBase, Protocol)

Common interface implemented by both roles backends.

list_roles method

async def list_roles(options: ListRolesOptions | None = None) -> ListRolesResult

List roles, paginated.

get_role method

async def get_role(role_id: str, *, expand: list[RoleExpand] | None = None) -> RoleInfo

Get a single role, optionally expanding users and/or permissions.

create_role method

async def create_role(role_id: str, role_input: CreateRoleInput | None = None) -> RoleInfo

Create a new role.

delete_role method

async def delete_role(role_id: str) -> None

Delete a role.

get_permissions method

async def get_permissions(role_id: str) -> RolePermissionsInfo

Get permissions assigned to a role.

set_permissions method

async def set_permissions(role_id: str, permissions: RolePermissionsInfo) -> RolePermissionsInfo

Replace all permissions assigned to a role.

grant_role method

async def grant_role(role_id: str, login: str) -> None

Assign a user to a role. OCAPI returns the user but we don't surface that.

revoke_role method

async def revoke_role(role_id: str, login: str) -> None

Unassign a user from a role.

ScapiRolesBackend

class ScapiRolesBackend

Business Manager roles backend implemented against the SCAPI Merchant Roles API.

Fields

Name	Type
name	Literal['scapi']

Functions

create_bm_role

async def create_bm_role(instance: B2CInstance, role_id: str, *, description: str | None = None) -> BmRole

Creates a new access role on an instance.

Parameters

Name	Type	Description
instance	B2CInstance	B2C instance.
role_id	str	Role ID to create.
description	str | None	Role description.

Returns: Created role.

create_roles_backend

def create_roles_backend(config: RolesBackendConfig) -> RolesBackend

Create a RolesBackend, resolving SCAPI/OCAPI per config.

delete_bm_role

async def delete_bm_role(instance: B2CInstance, role_id: str) -> None

Deletes an access role from an instance.

System roles (e.g. "Administrator", "Support") cannot be deleted.

Parameters

Name	Type	Description
instance	B2CInstance	B2C instance.
role_id	str	Role ID to delete.

get_bm_role

async def get_bm_role(instance: B2CInstance, role_id: str, options: GetBmRoleOptions | None = None) -> BmRole

Gets details of a specific access role.

Parameters

Name	Type	Description
instance	B2CInstance	B2C instance to query.
role_id	str	Role ID (e.g. "Administrator").
options	GetBmRoleOptions | None	Expand options.

Returns: Role details.

get_bm_role_permissions

async def get_bm_role_permissions(instance: B2CInstance, role_id: str) -> BmRolePermissions

Gets permissions assigned to an access role.

Parameters

Name	Type	Description
instance	B2CInstance	B2C instance.
role_id	str	Role ID.

Returns: Role permissions object.

grant_bm_role

async def grant_bm_role(instance: B2CInstance, role_id: str, login: str) -> dict[str, Any]

Assigns a user to an access role on an instance.

Parameters

Name	Type	Description
instance	B2CInstance	B2C instance.
role_id	str	Role ID to grant.
login	str	User login (email).

Returns: The user object after assignment.

list_bm_roles

async def list_bm_roles(instance: B2CInstance, options: ListBmRolesOptions | None = None) -> BmRoles

Lists all access roles on a B2C Commerce instance.

Parameters

Name	Type	Description
instance	B2CInstance	B2C instance to query.
options	ListBmRolesOptions | None	Pagination options.

Returns: Roles collection with pagination info.

revoke_bm_role

async def revoke_bm_role(instance: B2CInstance, role_id: str, login: str) -> None

Unassigns a user from an access role on an instance.

Parameters

Name	Type	Description
instance	B2CInstance	B2C instance.
role_id	str	Role ID to revoke.
login	str	User login (email).

set_bm_role_permissions

async def set_bm_role_permissions(instance: B2CInstance, role_id: str, permissions: BmRolePermissions) -> BmRolePermissions

Sets (replaces) all permissions for an access role.

This is a full replacement -- all existing permissions are replaced with the provided set.

Parameters

Name	Type	Description
instance	B2CInstance	B2C instance.
role_id	str	Role ID.
permissions	BmRolePermissions	Complete permissions object.

Returns: Updated permissions.

Attributes

BmRole

BmRole = dict[str, Any]

BmRolePermissions

BmRolePermissions = dict[str, Any]

BmRoles

BmRoles = dict[str, Any]

RoleExpand

RoleExpand = Literal['users', 'permissions']

RolePermissionsInfo

RolePermissionsInfo = dict[str, Any]

RolesBackendConfig

RolesBackendConfig = DualBackendConfig

ScapiRolesBackendConfig

ScapiRolesBackendConfig = ScapiBackendCtorConfig