---
editLink: false
lastUpdated: false
outline: [2, 3]
---

<!-- Generated by python/b2c-tooling-sdk/scripts/generate_api_docs.py. Do not edit. -->

# 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`](/python/api/operations/bm_roles#list-bm-roles) -- List all access roles on an instance
- [`get_bm_role`](/python/api/operations/bm_roles#get-bm-role) -- Get role details with optional expansion
- [`create_bm_role`](/python/api/operations/bm_roles#create-bm-role) -- Create a new access role
- [`delete_bm_role`](/python/api/operations/bm_roles#delete-bm-role) -- Delete an access role

## User Assignment

- [`grant_bm_role`](/python/api/operations/bm_roles#grant-bm-role) -- Assign a user to a role
- [`revoke_bm_role`](/python/api/operations/bm_roles#revoke-bm-role) -- Unassign a user from a role

## Permissions

- [`get_bm_role_permissions`](/python/api/operations/bm_roles#get-bm-role-permissions) -- Get permissions for a role
- [`set_bm_role_permissions`](/python/api/operations/bm_roles#set-bm-role-permissions) -- Replace all permissions for a role

## Usage

```python
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`](/python/api/operations/bm_roles#create-roles-backend) resolves a [`RolesBackend`](/python/api/operations/bm_roles#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 {#createroleinput}

```python
class CreateRoleInput
```

Options for [`RolesBackend.create_role`](/python/api/operations/bm_roles#rolesbackend-create-role).

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `description` | `str \| None` | `None` |

### GetBmRoleOptions {#getbmroleoptions}

```python
class GetBmRoleOptions
```

Options for getting a BM role.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `expand` | `Sequence[str] \| None` | `None` |

### ListBmRolesOptions {#listbmrolesoptions}

```python
class ListBmRolesOptions
```

Options for listing BM roles.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `start` | `int \| None` | `None` |
| `count` | `int \| None` | `None` |

### ListRolesOptions {#listrolesoptions}

```python
class ListRolesOptions
```

Options for [`RolesBackend.list_roles`](/python/api/clients#list-roles).

**Fields**

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

### ListRolesResult {#listrolesresult}

```python
class ListRolesResult
```

Paginated result of [`RolesBackend.list_roles`](/python/api/clients#list-roles).

**Fields**

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

### OcapiRolesBackend {#ocapirolesbackend}

```python
class OcapiRolesBackend
```

Business Manager roles backend implemented against the OCAPI Data API.

**Fields**

| Name | Type |
| --- | --- |
| `name` | `Literal['ocapi']` |

### RoleInfo {#roleinfo}

```python
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 {#rolesbackend}

```python
class RolesBackend(BackendBase, Protocol)
```

Common interface implemented by both roles backends.

#### list_roles <Badge type="info" text="method" /> {#rolesbackend-list-roles}

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

List roles, paginated.

#### get_role <Badge type="info" text="method" /> {#rolesbackend-get-role}

```python
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 <Badge type="info" text="method" /> {#rolesbackend-create-role}

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

Create a new role.

#### delete_role <Badge type="info" text="method" /> {#rolesbackend-delete-role}

```python
async def delete_role(role_id: str) -> None
```

Delete a role.

#### get_permissions <Badge type="info" text="method" /> {#rolesbackend-get-permissions}

```python
async def get_permissions(role_id: str) -> RolePermissionsInfo
```

Get permissions assigned to a role.

#### set_permissions <Badge type="info" text="method" /> {#rolesbackend-set-permissions}

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

Replace all permissions assigned to a role.

#### grant_role <Badge type="info" text="method" /> {#rolesbackend-grant-role}

```python
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 <Badge type="info" text="method" /> {#rolesbackend-revoke-role}

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

Unassign a user from a role.

### ScapiRolesBackend {#scapirolesbackend}

```python
class ScapiRolesBackend
```

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

**Fields**

| Name | Type |
| --- | --- |
| `name` | `Literal['scapi']` |

## Functions

### create_bm_role {#create-bm-role}

```python
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 {#create-roles-backend}

```python
def create_roles_backend(config: RolesBackendConfig) -> RolesBackend
```

Create a [`RolesBackend`](/python/api/operations/bm_roles#rolesbackend), resolving SCAPI/OCAPI per `config`.

### delete_bm_role {#delete-bm-role}

```python
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 {#get-bm-role}

```python
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 {#get-bm-role-permissions}

```python
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 {#grant-bm-role}

```python
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 {#list-bm-roles}

```python
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 {#revoke-bm-role}

```python
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 {#set-bm-role-permissions}

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

```python
BmRole = dict[str, Any]
```

### BmRolePermissions {#bmrolepermissions}

```python
BmRolePermissions = dict[str, Any]
```

### BmRoles {#bmroles}

```python
BmRoles = dict[str, Any]
```

### RoleExpand {#roleexpand}

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

### RolePermissionsInfo {#rolepermissionsinfo}

```python
RolePermissionsInfo = dict[str, Any]
```

### RolesBackendConfig {#rolesbackendconfig}

```python
RolesBackendConfig = DualBackendConfig
```

### ScapiRolesBackendConfig {#scapirolesbackendconfig}

```python
ScapiRolesBackendConfig = ScapiBackendCtorConfig
```