B2c Bm Users Roles

B2C Business Manager Users, Roles, and Access Keys

Use the b2c bm commands to administer instance-level Business Manager resources (users, roles, access keys) over SCAPI. These commands target a specific Commerce Cloud instance — pass --server/-s or set the active instance in dw.json first.

Tip: If b2c is not installed globally, use npx @salesforce/b2c-cli instead (e.g., npx @salesforce/b2c-cli bm whoami).

For Account Manager user/role/client management (cross-instance, scoped to tenants), see the b2c-cli:b2c-am skill instead.

API Backend

bm users (list, get, portable search, update, delete) and bm roles (all subcommands including permissions) run over the SCAPI Merchant Users / Merchant Roles APIs. Configure shortCode, tenantId, and the sfcc.users(.rw) / sfcc.roles(.rw) scopes to use SCAPI. Search is implemented by filtering the paginated SCAPI user listing.

OCAPI-only operations as of B2C Commerce release 26.8 (no current live SCAPI equivalent, unavailable on OCAPI-disabled instances): raw bm users search --query JSON, bm whoami, and bm access-key *. auto uses the temporary OCAPI compatibility path. Explicit SCAPI mode fails before contacting OCAPI and directs the user to --api-backend ocapi until support becomes available.

OCAPI is deprecated and disabled on newer instances. --api-backend auto (the default) falls back on safe SCAPI capability/auth/request rejections; force a backend with --api-backend scapi|ocapi if needed. SCAPI updates disabled by reading the current user and preserving its writable fields through PUT because PATCH omits that field.

Authentication

The CLI auto-discovers the target instance and credentials from SFCC_* environment variables, dw.json in the current or parent directories, ~/.mobify, package.json, and configuration plugins. Flags like --server, --client-id, and --client-secret are usually unnecessary — only pass them to override what's auto-detected. Run b2c setup inspect to see the resolved configuration and which source provided each value. For precedence and troubleshooting, see the b2c-cli:b2c-config skill.

As of release 26.8, SCAPI Admin APIs require client credentials or JWT Bearer and do not support browser-based user auth. User auth continues to work through OCAPI and WebDAV, and auto selects OCAPI for that flow. Explicit SCAPI fails with actionable guidance. A handful of OCAPI endpoints require a real BM user identity and default to user auth.

Override the default with --auth-methods client-credentials (or --client-secret flags) when your service-client setup is configured to issue user-bearing tokens.

Business Manager Roles

BM roles are instance-level Business Manager access roles (e.g. Administrator, Support, plus any custom roles).

# list roles on the configured instance
b2c bm roles list

# target a different instance
b2c bm roles list --server my-sandbox.demandware.net

# get role details, including assigned users
b2c bm roles get Administrator --expand users

# create a custom role
b2c bm roles create MyEditor --description "Custom role for content editors"

# delete a custom role (system roles cannot be deleted)
b2c bm roles delete MyEditor

# assign / unassign a user
b2c bm roles grant user@example.com --role Administrator
b2c bm roles revoke user@example.com --role Administrator

# all commands accept --json for machine-readable output
b2c bm roles list --json

Role Permissions

Permissions use a file-based get/set workflow because the API replaces the entire permission set on each write.

# view a permission summary
b2c bm roles permissions get Administrator

# export to a JSON file for editing
b2c bm roles permissions get Administrator --output admin-perms.json

# edit the file, then apply
b2c bm roles permissions set Administrator --file admin-perms.json

The permissions JSON has four sections: functional, module, locale, and webdav. Each can be scoped to organization, site, or unscoped depending on the permission type.

Business Manager Users

These commands cover the full lifecycle — create/read/search/update/delete — for BM users, plus the per-user access-key administration below. Note that bm users create is a create-or-replace that only works on instances configured to allow local BM users; most production instances use SSO with Account Manager and reject it with LocalUserCreationException, in which case users are provisioned in Account Manager and managed here for the rest of their lifecycle.

# list (default 25)
b2c bm users list
b2c bm users list --count 50 --start 50            # pagination
b2c bm users list --extended                       # add lastLogin, externalId
b2c bm users list --columns login,email,lastLogin  # custom column set

# get one user by login (email)
b2c bm users get user@example.com

# create a user (create-or-replace; --email required, --role repeatable)
# only on instances that allow local users — else LocalUserCreationException
b2c bm users create user@example.com --email user@example.com
b2c bm users create user@example.com --email user@example.com --first-name Jane --last-name Doe --role Administrator

# search by attribute (any combination of flags)
b2c bm users search --search-phrase smith
b2c bm users search --login user@example.com
b2c bm users search --locked --sort-by last_login_date --sort-order desc
b2c bm users search --query '{"text_query":{"fields":["login"],"search_phrase":"foo"}}'

# update non-identity fields (locale, external_id, disabled, name)
b2c bm users update user@example.com --disabled
b2c bm users update user@example.com --no-disabled --preferred-ui-locale en_US
b2c bm users update user@example.com --first-name Jane --last-name Doe

# delete (prompts for confirmation; --force to skip)
b2c bm users delete user@example.com
b2c bm users delete user@example.com --force --json

Cannot be updated via update: the locked flag and the user password (those are governed by AM/SSO).

Whoami — Identify the Current BM User

bm whoami calls GET /users/this and returns the BM user the OAuth token resolves to. Useful for verifying which identity will be used for downstream commands and for sanity-checking that a token actually carries a user claim.

b2c bm whoami
b2c bm whoami --json

Defaults to browser-based user-auth — a fresh shell will trigger an b2c auth login flow. Once logged in, the saved session is reused across commands until it expires.

Access Keys (WebDAV, OCAPI, Storefront)

Access keys let SSO-managed BM users authenticate to non-OAuth surfaces (WebDAV, classic OCAPI/SCAPI Basic auth, or Storefront diagnostics). Three scopes exist; pick the one matching the surface you need to use.

[LOGIN] is optional on every access-key command — when omitted, the CLI calls bm whoami first and operates on your own user. Passing an explicit login lets administrators manage someone else's keys (requires Manage_Users_Access_Keys permission).

# get access-key state for the current user (defaults to WEBDAV_AND_STUDIO)
b2c bm access-key get
b2c bm access-key get --scope STOREFRONT
b2c bm access-key get user@example.com --scope AGENT_USER_AND_OCAPI

# create or rotate an access key — the secret is shown ONCE at creation
b2c bm access-key create
b2c bm access-key create --scope STOREFRONT
b2c bm access-key create --json | jq -r '.access_key'

# enable / disable an existing key
b2c bm access-key set --enabled
b2c bm access-key set --no-enabled
b2c bm access-key set user@example.com --scope STOREFRONT --enabled

# delete (prompts for confirmation; --force to skip)
b2c bm access-key delete
b2c bm access-key delete --scope STOREFRONT --force

Important: the access_key value is only returned in the response of create. Subsequent get calls do not return it. If you lose the value, run create again — the previous key is removed automatically.

Common Workflows

Rotate my own WebDAV password (no admin privileges needed)

b2c bm access-key create
# record the printed access_key — it's the new password for WebDAV/IMPEX

Audit users with admin role and stale logins

b2c bm roles get Administrator --expand users --json | jq '.users[].login'
b2c bm users search --sort-by last_login_date --sort-order asc --json

Provision a new custom role and assign one user

b2c bm roles create MyEditor --description "Content editors"
b2c bm roles permissions get MyEditor --output role.json
# edit role.json
b2c bm roles permissions set MyEditor --file role.json
b2c bm roles grant editor@example.com --role MyEditor

Cycle access keys for an SSO user (admin)

# disable temporarily
b2c bm access-key set user@example.com --scope WEBDAV_AND_STUDIO --no-enabled

# rotate
b2c bm access-key create user@example.com --scope WEBDAV_AND_STUDIO

Common Patterns

• All list/search commands support --columns, --extended / -x, and --json.
• bm users and bm roles use OCAPI pagination: --count/-n and --start. AM commands use --size/--page instead — don't mix them up.
• Destructive commands (bm users delete, bm access-key delete) prompt for confirmation. Use --force for non-interactive scripts. --json mode skips the prompt automatically.
• When a service client cannot resolve a BM user (e.g. AM-only credential), whoami and access-key commands return UserNotAvailableException from the API — re-run with --user-auth or b2c auth login first.

More

See b2c bm --help, b2c bm users --help, and b2c bm access-key --help for the full flag list. The OCAPI Data API user resource documentation describes the underlying endpoints and their fault codes.