description	Set up authentication for the B2C CLI including Account Manager API clients, OCAPI permissions, and WebDAV access keys.

Authentication Setup

This guide covers setting up authentication for the B2C CLI, including Account Manager API clients, OCAPI permissions, and WebDAV access.

Overview

The CLI uses different authentication mechanisms depending on the operation:

Operation	Auth Method	Setup Required
Code deploy, watch (file upload)	WebDAV (Basic Auth or OAuth)	WebDAV Access
Code list, activate, delete	OAuth + OCAPI	API Client + OCAPI
Jobs, Sites	OAuth + OCAPI	API Client + OCAPI
SCAPI commands (schemas, custom-apis, eCDN)	OAuth + SCAPI scopes	API Client + SCAPI Scopes
CIP analytics (`cip query`, `cip report`)	OAuth + Client Credentials	API Client + Salesforce Commerce API role + tenant filter
SLAS client management	OAuth	None (uses built-in client) or API Client
Sandbox management	OAuth	None (uses built-in client) or API Client
Account Manager	OAuth	None (uses built-in client) or API Client
MRT commands	MRT API Key	MRT API Key

::: tip Zero-Config for Platform Commands Sandbox, SLAS, and Account Manager commands work out of the box without any client configuration. The CLI includes a built-in public client that authenticates via browser login (implicit flow). You only need to configure an API client if you want to use client credentials for automation/CI or need specific scopes. :::

::: tip Each CLI command page documents its specific authentication requirements. See the CLI Reference for details. :::

Account Manager API Client

Most CLI operations require an Account Manager API Client. This is configured in the Salesforce Commerce Cloud Account Manager.

Authentication Methods

The CLI supports five authentication methods:

Method	When Used	Role Configuration
User Authentication	When `--user-auth` is passed, or when only a client ID is provided (no secret)	Roles configured on your user account
Client Credentials	When both `--client-id` and `--client-secret` are provided	Roles configured on the API client
JWT Bearer	When `--jwt-cert` and `--jwt-key` are provided (certificate-based authentication)	Roles configured on the API client
Stateful User Authentication	After running `b2c auth login` — browser-based login, token stored and reused	Roles configured on your user account
Stateful Client Authentication	After running `b2c auth client` — client credentials login, token stored and reused	Roles configured on the API client

User Authentication opens a browser for interactive login and uses roles assigned to your user account. This is ideal for development and manual operations. Use --user-auth as a shorthand for --auth-methods implicit on any OAuth command.

Client Credentials uses the API client's secret for non-interactive authentication. This is ideal for CI/CD pipelines and automation.

JWT Bearer uses a public/private certificate pair for secure authentication without storing client secrets. This is ideal for production environments and CI/CD where you want stronger security. See JWT Authentication for details.

Stateful User Auth uses b2c auth login to open a browser for interactive login once, then stores the session on disk. Subsequent commands automatically use the stored token when it is present and valid, without re-opening the browser. Clear the session with b2c auth logout. See Auth Commands for details.

Stateful Client Auth uses b2c auth client to authenticate once with client credentials (or user/password), store the session, and reuse it across subsequent commands without passing credentials each time. Mirrors the sfcc-ci client:auth workflow. Use --renew to enable automatic token renewal via b2c auth client renew. See Auth Commands for details.

::: warning Stateful vs Stateless Precedence The stored session is used only when the token is valid and no explicit auth flags are provided. The CLI falls back to stateless auth when:

The stored token is expired or invalid — a warning suggests b2c auth client renew (if renewable) or b2c auth client / b2c auth login to re-authenticate.
Explicit stateless auth flags are passed (--client-secret, --user-auth, or --auth-methods) — a warning lists the flags that triggered the override. Remove them to use the stored session. Note that --client-id alone does not force stateless; the stored session is used if the client ID matches.

To opt out of stateful auth entirely, run b2c auth logout to clear the stored session. The CLI will then use stateless auth exclusively. :::

::: tip For Account Manager operations that require user-level roles (organization and API client management), use --user-auth to authenticate with your user account. See Account Manager Authentication for per-subtopic role requirements. :::

Creating an API Client

Log in to Account Manager.
Navigate to API Client in the left menu.
Click Add API Client.
Fill in the required fields:
- Display Name: A descriptive name (e.g., "B2C CLI")
- Password: A strong client secret (save this securely for Client Credentials auth)
Configure the Token Endpoint Auth Method:
- client_secret_basic for client credentials flow
- private_key_jwt for JWT Bearer authentication (certificate-based)

::: tip Certificate-Based Authentication For enhanced security, use JWT Bearer authentication instead of client secrets. This requires uploading a certificate to the API client and using the --jwt-cert and --jwt-key flags. See JWT Authentication for setup instructions. :::

::: warning For client credentials with secrets, only client_secret_basic is supported. client_secret_post isn't currently supported. :::

Assigning Roles

Roles grant permission to perform specific operations. Roles are configured differently depending on your authentication method.

Understanding Roles and Tenant Filters

Most roles require a tenant filter that specifies which tenants/realms the role applies to. This is configured alongside the role assignment.

Role	Operations	Notes
`Salesforce Commerce API`	SCAPI commands and CIP analytics commands	API clients only. Requires a tenant filter.
`Sandbox API User`	ODS management, SLAS client management	Requires tenant filter with realm/org IDs.
`SLAS Organization Administrator`	SLAS client management (user auth only)	User accounts only. Requires a tenant filter.

For Client Credentials (Roles on API Client)

Under the API Client's Roles section:

Add roles needed for your operations
For each role, configure the tenant filter with the tenant IDs (for example, zzxy_prd) or realm IDs you need to access

Important: The Salesforce Commerce API role is currently only available for API Clients, not user accounts.

For User Authentication (roles on User)

In Account Manager, navigate to your user account and add roles. Note that some operations require Client Credentials authentication.

Configuring Scopes

Under Default Scopes, add the following scopes based on your needs:

Scope	Purpose
`mail`	Required for user info in authentication flows
`roles`	Critical - returns role information in the token
`tenantFilter`	Critical - returns tenant access information in the token
`openid`	Required for OpenID Connect

For SCAPI commands, also add the relevant API scopes:

Scope	Commands	Reference
`sfcc.cdn-zones`	eCDN read operations	eCDN Commands
`sfcc.cdn-zones.rw`	eCDN write operations	eCDN Commands
`sfcc.scapi-schemas`	SCAPI schema browsing	SCAPI Schemas
`sfcc.custom-apis`	Custom API status	Custom APIs

Note: Do NOT add SALESFORCE_COMMERCE_API as a scope. This is a role, not a scope.

See the individual CLI command pages for complete scope requirements.

Configuring Tenant Filter

For ODS, SLAS, and SCAPI operations, your API client's roles must have a tenant filter configured:

In Account Manager, go to the API Client settings
Under each role (for example, Salesforce Commerce API, Sandbox API User), find the Tenant Filter
Add the tenant IDs (for example, zzxy_prd) or organization IDs you need to access

The tenant filter restricts which tenants/realms the role applies to.

Redirect URLs

For User Authentication (implicit flow), configure redirect URLs in your API client:

Redirect URL	Purpose
`http://localhost:8080`	Required for B2C CLI user authentication
`https://admin.dx.commercecloud.salesforce.com/oauth2-redirect.html`	Optional - enables ODS Swagger interface with same client

Note: Redirect URLs are not required for API clients using only Client Credentials or JWT Bearer authentication.

::: tip Running Behind a Proxy If you're running the CLI behind a proxy where localhost:8080 isn't reachable by the browser, set SFCC_REDIRECT_URI to the proxy URL (e.g., https://proxy.example.com:8080). The proxy should forward traffic to the CLI's local server. You can also change the local server port with SFCC_OAUTH_LOCAL_PORT. Make sure to add your proxy URL to the API client's redirect URLs in Account Manager. :::

JWT Authentication (Certificate-Based)

JWT Bearer authentication (RFC 7523) provides a more secure alternative to client secrets by using public/private certificate pairs. This is ideal for production environments and CI/CD pipelines where you want to avoid storing sensitive secrets.

How It Works

You generate a certificate pair (public certificate + private key)
You register the public certificate in Account Manager
The CLI uses the private key to sign JWT tokens for authentication
Account Manager verifies the signature using your registered certificate

Benefits

More secure: Private key never leaves your machine
No secrets to leak: No client secret to store or compromise
Better for CI/CD: Certificates can be rotated without updating secrets across pipelines
Industry standard: Implements OAuth 2.0 JWT Bearer (RFC 7523)

Setup Instructions

Step 1: Generate Certificate Pair

Generate an RSA certificate pair using OpenSSL:

openssl req -x509 -newkey rsa:4096 \
  -keyout key.pem \
  -out cert.pem \
  -days 365 \
  -nodes \
  -subj "/CN=B2C CLI"

This creates two files:

cert.pem - Public certificate (upload to Account Manager)
key.pem - Private key (keep secure on your machine)

::: tip Encrypted Keys For additional security, generate an encrypted private key by omitting -nodes and adding a passphrase when prompted. You'll provide the passphrase via --jwt-passphrase when using the CLI. :::

Step 2: Register Certificate in Account Manager

Log in to Account Manager
Navigate to API Client and select your client
Set Token Endpoint Auth Method to private_key_jwt
Upload cert.pem in the Certificates section
Save changes

::: tip Multiple Certificates per Client You can register multiple certificates for the same API client. This is useful for:

Team collaboration: Each developer generates their own key pair and registers their certificate
Key rotation: Add a new certificate before removing the old one (zero downtime)
Multi-environment: Different certificates for CI/CD, staging, production

Account Manager will verify JWT signatures against all registered certificates, so each team member can authenticate with their own private key while sharing the same client ID. :::

Step 3: Configure CLI

You can provide JWT credentials via CLI flags, environment variables, or configuration files.

Using CLI flags:

b2c code list \
  --client-id your-client-id \
  --jwt-cert ./cert.pem \
  --jwt-key ./key.pem

Using environment variables:

export SFCC_CLIENT_ID=your-client-id
export SFCC_JWT_CERT=/path/to/cert.pem
export SFCC_JWT_KEY=/path/to/key.pem

b2c code list

Using dw.json:

{
  "hostname": "your-instance.demandware.net",
  "client-id": "your-client-id",
  "jwt-cert-path": "./cert.pem",
  "jwt-key-path": "./key.pem"
}

For encrypted keys:

b2c code list \
  --client-id your-client-id \
  --jwt-cert ./cert.pem \
  --jwt-key ./key.pem \
  --jwt-passphrase "your-passphrase"

# Or via environment variable
export SFCC_JWT_PASSPHRASE=your-passphrase

Authentication Priority

JWT authentication is tried after client credentials (if client secret is available) but before implicit flow:

client-credentials - Uses client secret if available
jwt - Uses JWT certificate if configured (no client secret)
implicit - Opens browser for user authentication

To force JWT authentication even when a client secret is configured:

b2c code list --auth-methods jwt

Troubleshooting

"JWT certificate file not found"

Verify the certificate path is correct
Use absolute paths or paths relative to current directory

"Invalid JWT private key"

Check that the key file is in PEM format
If encrypted, ensure you provide the correct passphrase via --jwt-passphrase

"JWT authentication failed (401)"

Verify the certificate is registered in Account Manager
Ensure the Token Endpoint Auth Method is set to private_key_jwt
Check that the client ID matches the API client with the registered certificate

"Invalid certificate format"

The certificate must be in PEM format (starts with -----BEGIN CERTIFICATE-----)
Regenerate the certificate using the OpenSSL command above

Security Best Practices

Keep private keys secure: Never commit key.pem to version control
Add to .gitignore: Include *.pem and *.key in your .gitignore
Use encrypted keys in production: Generate keys with passphrases for production use
Rotate certificates regularly: Generate new certificates periodically (every 90-365 days)
Store passphrases securely: Use secret managers for passphrases in CI/CD

OCAPI Configuration

For operations that interact with B2C Commerce instances (code deployment, jobs, sites), you need to configure OCAPI permissions on each instance.

Configuring OCAPI in Business Manager

Log in to Business Manager
Navigate to Administration > Site Development > Open Commerce API Settings
Select the Data API type
Add a configuration for your client ID

Example OCAPI Configuration

{
  "_v": "24.5",
  "clients": [
    {
      "client_id": "your-client-id",
      "resources": [
        {
          "resource_id": "/code_versions",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/code_versions/*",
          "methods": ["get", "put", "patch", "delete"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/jobs/*/executions",
          "methods": ["post"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/jobs/*/executions/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/job_execution_search",
          "methods": ["post"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/sites",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/sites/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        }
      ]
    }
  ]
}

Minimal Configuration by Feature

Code management only:

{
  "resource_id": "/code_versions",
  "methods": ["get"]
},
{
  "resource_id": "/code_versions/*",
  "methods": ["get", "put", "patch", "delete"]
}

Job execution only:

{
  "resource_id": "/jobs/*/executions",
  "methods": ["post"]
},
{
  "resource_id": "/jobs/*/executions/*",
  "methods": ["get"]
},
{
  "resource_id": "/job_execution_search",
  "methods": ["post"]
}

Site listing only:

{
  "resource_id": "/sites",
  "methods": ["get"]
},
{
  "resource_id": "/sites/*",
  "methods": ["get"]
}

SCAPI Authentication

SCAPI commands (eCDN, SCAPI schemas, custom APIs) require OAuth authentication with specific roles and scopes.

Required Setup

Role: Assign the Salesforce Commerce API role to your API client with appropriate tenant filter
Scopes: Add required SCAPI scopes to your API client's Default Scopes

Scopes by Command

Command	Required Scope	Reference
`b2c scapi schemas list/get`	`sfcc.scapi-schemas`	SCAPI Schemas
`b2c scapi custom status`	`sfcc.custom-apis`	Custom APIs
`b2c ecdn` (read operations)	`sfcc.cdn-zones`	eCDN
`b2c ecdn` (write operations)	`sfcc.cdn-zones.rw`	eCDN

The CLI automatically requests these scopes. Your API client must have them in the Default Scopes list.

::: tip For detailed authentication requirements including specific scopes for each command, see the individual CLI command reference pages. :::

Configuration

# Set credentials
export SFCC_CLIENT_ID=my-client
export SFCC_CLIENT_SECRET=my-secret
export SFCC_TENANT_ID=zzxy_prd
export SFCC_SHORTCODE=kv7kzm78

# Example: List SCAPI schemas
b2c scapi schemas list

WebDAV Access

WebDAV is required for file upload operations (code deploy, code watch, webdav commands).

Option A: Basic Authentication (Recommended)

Use your Business Manager username and a WebDAV access key. These credentials provide better performance for file operations.

In Business Manager, go to Administration > Organization > Users
Select your user
Generate or view your WebDAV Access Key

See Configure WebDAV File Access for detailed instructions.

export SFCC_USERNAME=your-bm-username
export SFCC_PASSWORD=your-webdav-access-key

Option B: OAuth-based WebDAV

If you prefer to use OAuth credentials for WebDAV (instead of basic auth), you must configure WebDAV Client Permissions:

Log in to Business Manager
Navigate to Administration > Organization > WebDAV Client Permissions
Add a JSON configuration for your API client ID:

{
  "clients": [
    {
      "client_id": "your-client-id",
      "permissions": [
        {"path": "/cartridges", "operations": ["read_write"]},
        {"path": "/impex", "operations": ["read_write"]},
        {"path": "/logs", "operations": ["read_write"]}
      ]
    }
  ]
}

Common paths for CLI operations:

Path	Operations
`/cartridges`	Code deployment
`/impex`	Site import/export
`/logs`	Log file access
`/catalogs/<catalog-id>`	Catalog file access
`/libraries/<library-id>`	Content library access

Note: This configuration is only needed when using OAuth for WebDAV. It isn’t required when using basic authentication with username/access key.

Managed Runtime API Key

MRT commands use a separate API key system.

Getting an MRT API Key

Log in to the Managed Runtime dashboard
Navigate to Account Settings > API Keys
Click Create API Key
Copy and save the key securely (it's only shown once)

Configuring the API Key

# Save credentials to ~/.mobify
b2c mrt save-credentials --user your-email@example.com --api-key your-mrt-api-key

# Or use an environment variable
export MRT_API_KEY=your-mrt-api-key

Quick Start Example

Here's a complete example for setting up CLI access:

1. Create API Client in Account Manager

Log in to Account Manager
Navigate to API Client > Add API Client
Configure:
- Display Name: B2C CLI
- Password: Generate a strong secret (save securely)
- Roles:
  - Salesforce Commerce API - add tenant filter with your tenant IDs
  - Sandbox API User - if using ODS (add tenant filter)
- Default Scopes: mail roles tenantFilter openid sfcc.cdn-zones
- Redirect URLs: http://localhost:8080 (for user authentication)

2. Configure OCAPI (for code list/activate/delete, jobs, sites)

Add the JSON configuration shown in OCAPI Configuration to enable code version and job APIs.

3. Configure WebDAV Access (for code deploy/watch, webdav commands)

Either:

Use your BM username + WebDAV access key (recommended), or
Configure WebDAV Client Permissions for OAuth

4. Set Environment Variables

# OAuth credentials
export SFCC_CLIENT_ID=your-client-id
export SFCC_CLIENT_SECRET=your-client-secret

# Instance (for OCAPI commands)
export SFCC_SERVER=your-instance.demandware.net

# SCAPI (for eCDN, schemas, custom-apis)
export SFCC_TENANT_ID=zzxy_prd
export SFCC_SHORTCODE=kv7kzm78

# WebDAV (if using BM credentials)
export SFCC_USERNAME=your-bm-username
export SFCC_PASSWORD=your-webdav-access-key

5. Test the Configuration

# Test OAuth + OCAPI
b2c code list

# Test WebDAV
b2c webdav ls --root=cartridges

# Test SCAPI
b2c scapi schemas list

Troubleshooting

"Unauthorized" errors

Verify your client ID and secret are correct
Check that OCAPI is configured for your client ID
Ensure the API client has the required roles

"Forbidden" on WebDAV operations

Check WebDAV Client Permissions in Business Manager
Verify your WebDAV access key is correct
Ensure the folder you're accessing is permitted

"Invalid scope" errors

Add the required scopes to your API client's Default Scopes
For SCAPI commands, ensure the relevant sfcc.* scopes are in Default Scopes
Verify that Default Scopes includes mail roles tenantFilter openid

Next Steps

Configuration - Learn about CLI configuration options
CLI Reference - Browse available commands

FilesExpand file tree

authentication.md

Latest commit

History

authentication.md

File metadata and controls

Authentication Setup

Overview

Account Manager API Client

Authentication Methods

Creating an API Client

Assigning Roles

Understanding Roles and Tenant Filters

For Client Credentials (Roles on API Client)

For User Authentication (roles on User)

Configuring Scopes

Configuring Tenant Filter

Redirect URLs

JWT Authentication (Certificate-Based)

How It Works

Benefits

Setup Instructions

Step 1: Generate Certificate Pair

Step 2: Register Certificate in Account Manager

Step 3: Configure CLI

Authentication Priority

Troubleshooting

Security Best Practices

OCAPI Configuration

Configuring OCAPI in Business Manager

Example OCAPI Configuration

Minimal Configuration by Feature

SCAPI Authentication

Required Setup

Scopes by Command

Configuration

WebDAV Access

Option A: Basic Authentication (Recommended)

Option B: OAuth-based WebDAV

Managed Runtime API Key

Getting an MRT API Key

Configuring the API Key

Quick Start Example

1. Create API Client in Account Manager

2. Configure OCAPI (for code list/activate/delete, jobs, sites)

3. Configure WebDAV Access (for code deploy/watch, webdav commands)

4. Set Environment Variables

5. Test the Configuration

Troubleshooting

"Unauthorized" errors

"Forbidden" on WebDAV operations

"Invalid scope" errors

Next Steps