b2c_tooling_sdk.operations.bm_users

Business Manager user operations for B2C Commerce instances.

Mirrors src/operations/bm-users/index.ts. Provides functions for querying and managing instance-level users via the OCAPI Data API. These are distinct from Account Manager users managed via operations/users.

Create-or-replace is supported via the backend's create_or_replace_user method (PUT), obtained from create_users_backend. On instances using SSO with Account Manager (the default for production) this is rejected with LocalUserCreationException -- local user creation must be enabled on the instance for it to succeed; otherwise provision users in Account Manager and use these operations for read/search/update/delete plus access-key administration.

Core user functions:

list_bm_users - List all users on an instance.
get_bm_user - Get a user by login.
whoami_bm_user - Get the currently authenticated user.
search_bm_users - Search users with filter expressions.
update_bm_user - Update user attributes (locale, external_id, disabled).
delete_bm_user - Delete a user from the instance.

Access keys (externally-managed users):

get_bm_user_access_key - Read access key details.
create_bm_user_access_key - Create / rotate an access key.
set_bm_user_access_key_enabled - Enable / disable an access key.
delete_bm_user_access_key - Delete an access key.

Classes

CreateUserInput

python

class CreateUserInput

Body for create/replace (PUT). login and email are required.

Fields

Name	Type	Default
`login`	`str`
`email`	`str`
`first_name`	`str \| None`	`None`
`last_name`	`str \| None`	`None`
`external_id`	`str \| None`	`None`
`password`	`str \| None`	`None`
`disabled`	`bool \| None`	`None`
`preferred_data_locale`	`str \| None`	`None`
`preferred_ui_locale`	`str \| None`	`None`
`roles`	`list[str] \| None`	`None`

ListBmUsersOptions

python

class ListBmUsersOptions

Options for listing BM users.

Fields

Name	Type	Default
`start`	`int \| None`	`None`
`count`	`int \| None`	`None`
`select`	`str \| None`	`None`

ListUsersOptions

python

class ListUsersOptions

Options for UsersBackend.list_users.

Fields

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

ListUsersResult

python

class ListUsersResult

Result of listing users -- paginated.

Fields

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

OcapiUsersBackend

python

class OcapiUsersBackend

Manages BM users through the legacy OCAPI Data API /users resource.

Fields

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

ScapiUsersBackend

python

class ScapiUsersBackend

Manages BM users through the SCAPI Merchant Users Admin API.

Fields

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

SearchBmUsersOptions

python

class SearchBmUsersOptions

Options for searching BM users.

Searchable fields per the Data API spec: login, email, first_name, last_name, external_id, last_login_date, is_locked, is_disabled.

Fields

Name	Type	Default
`query`	`Any`	`None`
`search_phrase`	`str \| None`	`None`
`login`	`str \| None`	`None`
`email`	`str \| None`	`None`
`locked`	`bool \| None`	`None`
`disabled`	`bool \| None`	`None`
`sort_by`	`str \| None`	`None`
`sort_order`	`Literal['asc', 'desc'] \| None`	`None`
`start`	`int \| None`	`None`
`count`	`int \| None`	`None`
`select`	`str \| None`	`None`

SearchUsersOptions

python

class SearchUsersOptions(ListUsersOptions)

Portable user search criteria supported by both backends.

Fields

Name	Type	Default
`query`	`Any`	`None`
`search_phrase`	`str \| None`	`None`
`login`	`str \| None`	`None`
`email`	`str \| None`	`None`
`locked`	`bool \| None`	`None`
`disabled`	`bool \| None`	`None`
`sort_by`	`str \| None`	`None`
`sort_order`	`Literal['asc', 'desc'] \| None`	`None`

UpdateBmUserChanges

python

class UpdateBmUserChanges

Updatable user fields for patch operations.

Note: locked and password cannot be modified via PATCH per the API spec.

Fields

Name	Type	Default
`disabled`	`bool \| None`	`None`
`email`	`str \| None`	`None`
`external_id`	`str \| None`	`None`
`first_name`	`str \| None`	`None`
`last_name`	`str \| None`	`None`
`preferred_data_locale`	`str \| None`	`None`
`preferred_ui_locale`	`str \| None`	`None`

UpdateUserChanges

python

class UpdateUserChanges

Patch fields. SCAPI uses camelCase; the OCAPI backend translates to snake_case.

Fields

Name	Type	Default
`email`	`str \| None`	`None`
`first_name`	`str \| None`	`None`
`last_name`	`str \| None`	`None`
`external_id`	`str \| None`	`None`
`disabled`	`bool \| None`	`None`
`preferred_data_locale`	`str \| None`	`None`
`preferred_ui_locale`	`str \| None`	`None`

UserInfo

python

class UserInfo

Canonical Business Manager user.

Field names match SCAPI (camelCase in TS, snake_case here); the OCAPI backend maps from OCAPI's own snake_case wire shape.

Fields

Name	Type	Default
`login`	`str`
`email`	`str \| None`	`None`
`first_name`	`str \| None`	`None`
`last_name`	`str \| None`	`None`
`external_id`	`str \| None`	`None`
`disabled`	`bool \| None`	`None`
`locked`	`bool \| None`	`None`
`last_login_date`	`str \| None`	`None`
`password_expiration_date`	`str \| None`	`None`
`password_modification_date`	`str \| None`	`None`
`preferred_data_locale`	`str \| None`	`None`
`preferred_ui_locale`	`str \| None`	`None`
`roles`	`list[str] \| None`	`None`
`raw`	`Any`	`None`

UsersBackend

python

class UsersBackend(BackendBase, Protocol)

Backend contract for BM user operations.

Merchant Users has no server-side search endpoint, so the SCAPI backend implements portable search criteria over its paginated user listing. Raw OCAPI query DSL, access keys, and whoami remain OCAPI-only.

list_users method

python

async def list_users(options: ListUsersOptions | None = None) -> ListUsersResult

List users, paginated.

search_users method

python

async def search_users(options: SearchUsersOptions | None = None) -> ListUsersResult

Search users using portable criteria.

get_user method

python

async def get_user(login: str) -> UserInfo

Get a single user by login.

create_or_replace_user method

python

async def create_or_replace_user(login: str, input: CreateUserInput) -> UserInfo

Create or fully replace a user.

update_user method

python

async def update_user(login: str, changes: UpdateUserChanges) -> UserInfo

Update fields on an existing user.

delete_user method

python

async def delete_user(login: str) -> None

Delete a user.

Functions

create_bm_user_access_key

python

async def create_bm_user_access_key(instance: B2CInstance, login: str, scope: str) -> BmAccessKeyDetails

Creates a single access key for an externally-managed user.

Replaces any existing key for the same scope. The returned object includes the newly-generated access_key value -- this is the only time it is returned, so callers should record it.

Parameters

Name	Type	Description
`instance`	`B2CInstance`	B2C instance.
`login`	`str`	User login.
`scope`	`str`	Access key scope.

Returns: Access key details (including the secret access_key value).

create_users_backend

python

def create_users_backend(config: UsersBackendConfig) -> UsersBackend

Create a UsersBackend, resolving SCAPI/OCAPI per config.

delete_bm_user

python

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

Deletes a user from an instance.

Parameters

Name	Type	Description
`instance`	`B2CInstance`	B2C instance.
`login`	`str`	User login.

delete_bm_user_access_key

python

async def delete_bm_user_access_key(instance: B2CInstance, login: str, scope: str) -> None

Deletes a single access key for an externally-managed user.

Parameters

Name	Type	Description
`instance`	`B2CInstance`	B2C instance.
`login`	`str`	User login.
`scope`	`str`	Access key scope.

get_bm_user

python

async def get_bm_user(instance: B2CInstance, login: str) -> BmUser

Gets a single user by login (email).

Parameters

Name	Type	Description
`instance`	`B2CInstance`	B2C instance.
`login`	`str`	User login.

Returns: User details.

get_bm_user_access_key

python

async def get_bm_user_access_key(instance: B2CInstance, login: str, scope: str) -> BmAccessKeyDetails

Gets a single access key for an externally-managed user.

Parameters

Name	Type	Description
`instance`	`B2CInstance`	B2C instance.
`login`	`str`	User login.
`scope`	`str`	Access key scope (one of `ACCESS_KEY_SCOPES`).

Returns: Access key details.

list_bm_users

python

async def list_bm_users(instance: B2CInstance, options: ListBmUsersOptions | None = None) -> BmUsers

Lists all users on a B2C Commerce instance.

Parameters

Name	Type	Description
`instance`	`B2CInstance`	B2C instance to query.
`options`	`ListBmUsersOptions \| None`	Pagination options.

Returns: Users collection with pagination info.

search_bm_users

python

async def search_bm_users(instance: B2CInstance, options: SearchBmUsersOptions | None = None) -> BmUserSearchResult

Searches users on an instance.

Supports either a fully-formed OCAPI query (options.query) or convenience flags (search_phrase, login, email, locked, disabled) which are combined into a bool_query. If no criteria are provided a match_all_query is used.

Parameters

Name	Type	Description
`instance`	`B2CInstance`	B2C instance.
`options`	`SearchBmUsersOptions \| None`	Search options.

Returns: User search result.

set_bm_user_access_key_enabled

python

async def set_bm_user_access_key_enabled(instance: B2CInstance, login: str, scope: str, enabled: bool) -> BmAccessKeyDetails

Enables or disables an existing access key for an externally-managed user.

Parameters

Name	Type	Description
`instance`	`B2CInstance`	B2C instance.
`login`	`str`	User login.
`scope`	`str`	Access key scope.
`enabled`	`bool`	Whether the access key should be enabled.

Returns: Updated access key details.

update_bm_user

python

async def update_bm_user(instance: B2CInstance, login: str, changes: UpdateBmUserChanges) -> BmUser

Updates an existing user.

The locked flag and the user password cannot be updated with this resource.

Parameters

Name	Type	Description
`instance`	`B2CInstance`	B2C instance.
`login`	`str`	User login.
`changes`	`UpdateBmUserChanges`	Fields to update.

Returns: Updated user.

whoami_bm_user

python

async def whoami_bm_user(instance: B2CInstance) -> BmUser

Returns details for the currently authenticated user.

Useful for verifying which BM identity is in use on an instance.

Parameters

Name	Type	Description
`instance`	`B2CInstance`	B2C instance.

Returns: Current user details (includes password expiration info).

Attributes

ACCESS_KEY_SCOPES

python

ACCESS_KEY_SCOPES = ('WEBDAV_AND_STUDIO', 'AGENT_USER_AND_OCAPI', 'STOREFRONT')

AccessKeyScope

python

AccessKeyScope = Literal['WEBDAV_AND_STUDIO', 'AGENT_USER_AND_OCAPI', 'STOREFRONT']

BmAccessKeyDetails

python

BmAccessKeyDetails = dict[str, Any]

BmUser

python

BmUser = dict[str, Any]

BmUserSearchResult

python

BmUserSearchResult = dict[str, Any]

BmUsers

python

BmUsers = dict[str, Any]

ScapiUsersBackendConfig

python

ScapiUsersBackendConfig = ScapiBackendCtorConfig

UsersBackendConfig

python

UsersBackendConfig = DualBackendConfig

b2c_tooling_sdk.operations.bm_users ​

Classes ​

CreateUserInput ​

ListBmUsersOptions ​

ListUsersOptions ​

ListUsersResult ​

OcapiUsersBackend ​

ScapiUsersBackend ​

SearchBmUsersOptions ​

SearchUsersOptions ​

UpdateBmUserChanges ​

UpdateUserChanges ​

UserInfo ​

UsersBackend ​

list_users method ​

search_users method ​

get_user method ​

create_or_replace_user method ​

update_user method ​

delete_user method ​

Functions ​

create_bm_user_access_key ​

create_users_backend ​

delete_bm_user ​

delete_bm_user_access_key ​

get_bm_user ​

get_bm_user_access_key ​

list_bm_users ​

search_bm_users ​

set_bm_user_access_key_enabled ​

update_bm_user ​

whoami_bm_user ​

Attributes ​

ACCESS_KEY_SCOPES ​

AccessKeyScope ​

BmAccessKeyDetails ​

BmUser ​

BmUserSearchResult ​

BmUsers ​

ScapiUsersBackendConfig ​

UsersBackendConfig ​

b2c_tooling_sdk.operations.bm_users

Classes

CreateUserInput

ListBmUsersOptions

ListUsersOptions

ListUsersResult

OcapiUsersBackend

ScapiUsersBackend

SearchBmUsersOptions

SearchUsersOptions

UpdateBmUserChanges

UpdateUserChanges

UserInfo

UsersBackend

list_users method

search_users method

get_user method

create_or_replace_user method

update_user method

delete_user method

Functions

create_bm_user_access_key

create_users_backend

delete_bm_user

delete_bm_user_access_key

get_bm_user

get_bm_user_access_key

list_bm_users

search_bm_users

set_bm_user_access_key_enabled

update_bm_user

whoami_bm_user

Attributes

ACCESS_KEY_SCOPES

AccessKeyScope

BmAccessKeyDetails

BmUser

BmUserSearchResult

BmUsers

ScapiUsersBackendConfig

UsersBackendConfig