Business Manager Commands

Commands for administering instance-level Business Manager resources. These are distinct from Account Manager commands which manage cross-instance identity.

API Backend

bm users and bm roles run over the SCAPI Merchant Users / Merchant Roles APIs. Configure shortCode, tenantId, and the sfcc.users(.rw) / sfcc.roles(.rw) scopes to use SCAPI. In auto mode, missing SCAPI coordinates select the temporary OCAPI compatibility backend instead of being required up front.

bash

# Default — uses SCAPI for users/roles
b2c bm users list
b2c bm roles get Administrator

Command	Backend	Scope
`bm users list/get/create/update/delete`	SCAPI	`sfcc.users.rw`
`bm users search` (portable flags)	SCAPI, client-side filtering over user pages	`sfcc.users` or `sfcc.users.rw`
`bm roles list/get/create/delete`	SCAPI	`sfcc.roles.rw`
`bm roles grant/revoke`	SCAPI	`sfcc.roles.rw`
`bm roles permissions get/set`	SCAPI	`sfcc.roles.rw`
`bm users search --query`	OCAPI only (raw OCAPI query DSL)	—
`bm whoami`	OCAPI only	—
`bm access-key *`	OCAPI only	—

Legacy OCAPI backend (deprecated)

OCAPI is deprecated and disabled on newer instances. The CLI defaults to --api-backend auto, which falls back to OCAPI on safe SCAPI capability/auth/request rejections. Force a backend if needed:

bash

b2c bm users list --api-backend scapi          # force SCAPI
b2c bm roles get Administrator --api-backend ocapi   # force the legacy OCAPI backend

Or set "api-backend": "scapi" in dw.json, or SFCC_API_BACKEND=scapi. As of B2C Commerce release 26.8, the live SCAPI schemas do not expose equivalents for bm users search --query, bm whoami, or bm access-key. In auto mode these use the temporary OCAPI compatibility path. Explicit SCAPI mode fails before contacting OCAPI and directs the user to --api-backend ocapi until platform support becomes available.

The SCAPI Users PATCH endpoint does not include the disabled field, so bm users update --disabled reads the current user and preserves its writable fields through SCAPI PUT.

Authentication

BM commands authenticate via OAuth against the configured Commerce Cloud instance. As of release 26.8, SCAPI supports client credentials and JWT Bearer for these commands. Browser-based user auth remains supported through OCAPI and WebDAV, not SCAPI:

Client credentials — for automation and CI/CD. Configure an Account Manager API client and grant it the OCAPI permissions listed below. Pass credentials via --client-id / --client-secret, the SFCC_CLIENT_ID / SFCC_CLIENT_SECRET environment variables, or dw.json.
User auth (browser) — for interactive OCAPI/WebDAV use. Pass --user-auth (or run b2c auth login once and reuse the saved session). In auto mode migrated operations select OCAPI; explicit SCAPI reports that browser user authentication is not supported by SCAPI Admin APIs as of release 26.8 and directs the user to system authentication or OCAPI.

A handful of endpoints require a real BM user identity and cannot use service-client tokens — the CLI defaults those to user-auth automatically:

Command group	Default auth	Why
`b2c bm roles ...`	client-credentials → jwt → implicit	OCAPI permissions for `/roles`
`b2c bm users {list,get,search,update,delete}`	client-credentials → jwt → implicit	OCAPI permissions for `/users`
`b2c bm whoami`	implicit (browser)	`/users/this` requires the token to resolve to a BM user
`b2c bm access-key ...`	implicit (browser)	Access-key endpoints require a valid user plus the `Manage_Users_Access_Keys` BM functional permission

Override the auto-defaulted user-auth with --auth-methods client-credentials (or --client-secret) when your service-client setup is configured to issue user-bearing tokens. The interactive defaults can also be skipped end-to-end by exporting SFCC_AUTH_METHODS=client-credentials,jwt in CI.

See the Authentication Guide for end-to-end setup, including the BM administration OCAPI snippet.

Required OCAPI Permissions

Add these resources to the Data API client configuration in Business Manager (Administration > Site Development > Open Commerce API Settings > Data API):

Resource	Methods	Used by
`/roles`	GET	`bm roles list`
`/roles/*`	GET, PUT, DELETE	`bm roles get/create/delete`
`/roles/*/users`	GET	`bm roles get --expand users`
`/roles//users/`	PUT, DELETE	`bm roles grant/revoke`
`/roles/*/permissions`	GET, PUT	`bm roles permissions get/set`
`/users`	GET	`bm users list`
`/users/*`	GET, PATCH, DELETE	`bm users get/update/delete`
`/users/this`	GET	`bm whoami`, `bm access-key` (optional login fallback)
`/users//access_key/`	GET, PUT, PATCH, DELETE	`bm access-key get/create/set/delete`
`/user_search`	POST	`bm users search`

For an importable JSON snippet covering all BM administration endpoints, see Minimal Configuration by Feature in the Authentication Guide.

Required BM Functional Permission

Access-key writes (bm access-key {create,set,delete}) additionally require the Manage_Users_Access_Keys BM functional permission on the user account performing the request. Grant it via Business Manager: Administration > Roles & Permissions. This is why the CLI defaults bm access-key commands to user-auth — service clients cannot carry BM functional permissions.

Configuration Examples

bash

# Interactive (browser login on first command, session reused after):
b2c auth login --instance my-sandbox
b2c bm whoami

# Client credentials (where supported):
export SFCC_CLIENT_ID=your-client-id
export SFCC_CLIENT_SECRET=your-client-secret
export SFCC_SERVER=my-sandbox.demandware.net
b2c bm users list

# Force user-auth on a command that defaults to client-credentials:
b2c bm users list --user-auth

# Force client-credentials on a command that defaults to user-auth (advanced):
b2c bm access-key get --auth-methods client-credentials

Roles

b2c bm roles — manage instance-level Business Manager access roles, user assignments, and role permissions.

b2c bm roles list

List all access roles on an instance.

bash

b2c bm roles list [--count <n>] [--start <n>] [--columns <cols>] [--extended]

Flag	Description
`--count`, `-n`	Number of roles to return (default 25)
`--start`	Start index for pagination (default 0)
`--columns`, `-c`	Comma-separated columns to display. Available: `id`, `description`, `userCount`, `userManager`
`--extended`, `-x`	Show all columns including extended fields

bash

b2c bm roles list
b2c bm roles list --server my-sandbox.demandware.net
b2c bm roles list --extended --json

b2c bm roles get

Get details of a specific access role.

bash

b2c bm roles get <role> [--expand <expansion>...]

Argument	Description
`role`	Role ID (e.g. `Administrator`)

Flag	Description
`--expand`, `-e`	Expansions to apply (`users`, `permissions`). Repeatable.

bash

b2c bm roles get Administrator
b2c bm roles get Administrator --expand users

b2c bm roles create

Create a new custom access role.

bash

b2c bm roles create <role> [--description <text>]

Argument	Description
`role`	Role ID to create

Flag	Description
`--description`, `-d`	Description for the role

bash

b2c bm roles create ContentEditor --description "Role for content editors"

WARNING

Reserved role IDs (Support, Business Support) cannot be created.

b2c bm roles delete

Delete a custom access role.

bash

b2c bm roles delete <role>

bash

b2c bm roles delete ContentEditor

WARNING

System roles (e.g. Administrator) cannot be deleted.

b2c bm roles grant

Assign a user to an access role.

bash

b2c bm roles grant <login> --role <role>

Flag	Description
`--role`, `-r`	Role ID to grant (required)

bash

b2c bm roles grant user@example.com --role Administrator

b2c bm roles revoke

Unassign a user from an access role.

bash

b2c bm roles revoke <login> --role <role>

bash

b2c bm roles revoke user@example.com --role Administrator

b2c bm roles permissions get

Get permissions for an access role.

bash

b2c bm roles permissions get <role> [--output <file>]

Flag	Description
`--output`, `-o`	Write full permissions JSON to a file for editing

bash

# View summary
b2c bm roles permissions get Administrator

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

# Get raw JSON
b2c bm roles permissions get Administrator --json

b2c bm roles permissions set

Set (replace) all permissions for an access role from a JSON file.

bash

b2c bm roles permissions set <role> --file <path>

Flag	Description
`--file`, `-f`	JSON file containing permissions (`role_permissions` schema) (required)

bash

b2c bm roles permissions get MyRole --output perms.json
# ... edit perms.json ...
b2c bm roles permissions set MyRole --file perms.json

WARNING

This command replaces all existing permissions for the role. Use permissions get --output first to ensure you have the complete set.

Permissions JSON Structure

The file follows the OCAPI role_permissions schema with four sections:

json

{
  "functional": {
    "organization": [{"name": "PERMISSION_NAME", "type": "functional", "value": "ACCESS"}],
    "site": []
  },
  "module": {
    "organization": [{"application": "bm", "name": "ModuleName", "type": "module", "system": true, "value": "ACCESS"}],
    "site": []
  },
  "locale": {
    "unscoped": [{"locale_id": "default", "type": "locale", "value": "ACCESS"}]
  },
  "webdav": {
    "unscoped": [{"folder": "Catalogs", "type": "webdav", "value": "ACCESS"}]
  }
}

Users

b2c bm users — query and manage instance-level Business Manager users via the OCAPI /users resource.

Local user creation is often disabled

b2c bm users create performs a create-or-replace. Most production instances use SSO with Account Manager and reject creating local BM users — the server responds with LocalUserCreationException ("creation of a local Business Manager user is not allowed with the current server settings"). Creation succeeds only when the instance is explicitly configured to allow local users; otherwise use Account Manager to provision users and manage them here (read/update/delete/search) plus access-key administration.

b2c bm users list

List all users on the instance.

bash

b2c bm users list [--count <n>] [--start <n>] [--columns <cols>] [--extended]

Flag	Description
`--count`, `-n`	Number of users to return (default 25)
`--start`	Start index for pagination (default 0)
`--columns`, `-c`	Comma-separated columns to display. Available: `login`, `email`, `name`, `disabled`, `locked`, `lastLogin`, `externalId`
`--extended`, `-x`	Include extended columns (`lastLogin`, `externalId`)

bash

b2c bm users list
b2c bm users list --count 100
b2c bm users list --extended --json
b2c bm users list --columns login,email,lastLogin

b2c bm users get

Get details of one user by login.

bash

b2c bm users get <login>

bash

b2c bm users get user@example.com
b2c bm users get user@example.com --json

b2c bm users search

Search users by login, email, name, lock state, or disabled state. Searchable fields per the Data API: login, email, first_name, last_name, external_id, last_login_date, is_locked, is_disabled.

bash

b2c bm users search [--search-phrase <text>] [--login <login>] [--email <email>] \
    [--locked] [--disabled] [--sort-by <field>] [--sort-order asc|desc] \
    [--query <json>] [--count <n>] [--start <n>] [--columns <cols>] [--extended]

Flag	Description
`--search-phrase`	Free-text phrase searched across login/email/first_name/last_name
`--login`	Match a specific login
`--email`	Match a specific email
`--locked` / `--no-locked`	Match locked / unlocked users
`--disabled` / `--no-disabled`	Match disabled / enabled users
`--sort-by`	Sort field (e.g. `last_login_date`)
`--sort-order`	`asc` or `desc`
`--query`	Raw OCAPI query JSON (overrides convenience flags)
`--count`, `-n`	Number of users to return (default 25)
`--start`	Start index for pagination (default 0)
`--columns`, `-c`	Comma-separated columns to display. Available: `login`, `email`, `name`, `disabled`, `locked`, `lastLogin`, `externalId`
`--extended`, `-x`	Include extended columns (`lastLogin`, `externalId`)

bash

b2c bm users search --search-phrase smith
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"}}'

b2c bm users create

Create a Business Manager user (create-or-replace via PUT /users/{login}). --email is required; the login argument is the user's login (typically their email).

WARNING

This succeeds only on instances configured to allow local BM users. On SSO/Account-Manager–only instances the server rejects it with LocalUserCreationException — provision the user in Account Manager instead. Because it is create-or-replace, running it against an existing login replaces that user's attributes.

bash

b2c bm users create <login> --email <email> [--first-name <name>] [--last-name <name>] \
    [--external-id <id>] [--password <password>] [--role <role>...] \
    [--disabled | --no-disabled] [--preferred-ui-locale <locale>] [--preferred-data-locale <locale>]

bash

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
b2c bm users create user@example.com --email user@example.com --role Administrator --role bm-admin
b2c bm users create user@example.com --email user@example.com --external-id ext-123

--password applies only to local users and is ignored for SSO/AM-managed accounts. --role is repeatable.

b2c bm users update

Update non-identity user fields. The locked flag and password cannot be updated through this command — those are governed by Account Manager / SSO.

bash

b2c bm users update <login> [--disabled | --no-disabled] [--first-name <name>] \
    [--last-name <name>] [--email <email>] [--external-id <id>] \
    [--preferred-ui-locale <locale>] [--preferred-data-locale <locale>]

bash

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

b2c bm users delete

Remove a user from the instance. Prompts for confirmation by default.

bash

b2c bm users delete <login> [--force]

Flag	Description
`--force`	Skip the confirmation prompt

bash

b2c bm users delete user@example.com
b2c bm users delete user@example.com --force --json

Whoami

b2c bm whoami — show the Business Manager user the current OAuth token resolves to. Calls GET /users/this.

bash

b2c bm whoami [--json]

Useful for verifying which BM identity is in use after b2c auth login, or for sanity-checking that a token actually carries a user claim.

bash

b2c bm whoami
b2c bm whoami --json | jq -r '.login'

TIP

This command defaults to browser-based user-auth — a fresh shell triggers b2c auth login. The saved session is reused across commands until it expires.

Access Keys

b2c bm access-key — manage WebDAV / OCAPI / Storefront access keys for SSO-managed (externally managed) Business Manager users. These keys let users authenticate to non-OAuth surfaces using their BM identity.

[LOGIN] is optional on every access-key command — when omitted, the CLI calls bm whoami first and operates on your own user.

Scopes

Scope	Used for
`WEBDAV_AND_STUDIO` (default)	WebDAV uploads (cartridge sync, IMPEX), Studio access
`AGENT_USER_AND_OCAPI`	Customer Service Center (CSC) and OCAPI Basic auth
`STOREFRONT`	Storefront diagnostic / agent login passwords

b2c bm access-key get

Get the current state of an access key.

bash

b2c bm access-key get [<login>] [--scope <scope>]

Argument	Description
`[login]`	User login (email). Defaults to the currently authenticated user.

Flag	Description
`--scope`	One of `WEBDAV_AND_STUDIO` (default), `AGENT_USER_AND_OCAPI`, `STOREFRONT`

bash

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

b2c bm access-key create

Create or rotate an access key. The secret value is returned only once, at creation — record it immediately.

bash

b2c bm access-key create [<login>] [--scope <scope>]

bash

b2c bm access-key create
b2c bm access-key create --scope STOREFRONT
b2c bm access-key create --json | jq -r '.access_key'

WARNING

The previous key for the same scope is removed automatically when a new one is created. The new access_key value is only returned in the response of create — subsequent get calls do not return it.

b2c bm access-key set

Enable or disable an existing access key.

bash

b2c bm access-key set [<login>] [--scope <scope>] (--enabled | --no-enabled)

Flag	Description
`--enabled` / `--no-enabled`	Enable or disable the key (required)

bash

b2c bm access-key set --enabled
b2c bm access-key set --no-enabled
b2c bm access-key set user@example.com --scope STOREFRONT --enabled

b2c bm access-key delete

Delete an access key. Prompts for confirmation by default.

bash

b2c bm access-key delete [<login>] [--scope <scope>] [--force]

Flag	Description
`--force`	Skip the confirmation prompt

bash

b2c bm access-key delete
b2c bm access-key delete --scope STOREFRONT --force
b2c bm access-key delete user@example.com --scope WEBDAV_AND_STUDIO

Common Workflows

Rotate my own WebDAV password

bash

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

Audit role assignments

bash

b2c bm roles get Administrator --expand users --json | jq '.users[].login'

Find inactive users

bash

b2c bm users search --sort-by last_login_date --sort-order asc --json

Provision a custom role and assign one user

bash

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 a user (admin)

bash

# 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

Business Manager Commands ​

API Backend ​

Authentication ​

Required OCAPI Permissions ​

Required BM Functional Permission ​

Configuration Examples ​

Roles ​

b2c bm roles list ​

b2c bm roles get ​

b2c bm roles create ​

b2c bm roles delete ​

b2c bm roles grant ​

b2c bm roles revoke ​

b2c bm roles permissions get ​

b2c bm roles permissions set ​

Permissions JSON Structure ​

Users ​

b2c bm users list ​

b2c bm users get ​

b2c bm users search ​

b2c bm users create ​

b2c bm users update ​

b2c bm users delete ​

Whoami ​

Access Keys ​

Scopes ​

b2c bm access-key get ​

b2c bm access-key create ​

b2c bm access-key set ​

b2c bm access-key delete ​

Common Workflows ​

Rotate my own WebDAV password ​

Audit role assignments ​

Find inactive users ​

Provision a custom role and assign one user ​

Cycle access keys for a user (admin) ​

Business Manager Commands

API Backend

Authentication

Required OCAPI Permissions

Required BM Functional Permission

Configuration Examples

Roles

b2c bm roles list

b2c bm roles get

b2c bm roles create

b2c bm roles delete

b2c bm roles grant

b2c bm roles revoke

b2c bm roles permissions get

b2c bm roles permissions set

Permissions JSON Structure

Users

b2c bm users list

b2c bm users get

b2c bm users search

b2c bm users create

b2c bm users update

b2c bm users delete

Whoami

Access Keys

Scopes

b2c bm access-key get

b2c bm access-key create

b2c bm access-key set

b2c bm access-key delete

Common Workflows

Rotate my own WebDAV password

Audit role assignments

Find inactive users

Provision a custom role and assign one user

Cycle access keys for a user (admin)