doc update

Author: clavery

docs/cli/auth.md

@@ -88,25 +88,29 @@ The CLI supports multiple authentication methods depending on the operation.
 
 ### Account Manager API Client (OAuth)
 
-Most instance operations require an Account Manager API Client. The CLI supports two OAuth flows:
+Most instance operations require an Account Manager API Client. The CLI supports two authentication methods:
 
-| Auth Method | Description | Use Case |
-|-------------|-------------|----------|
-| User Authentication | Interactive browser-based login | Development, manual operations |
-| Client Credentials | Non-interactive with client ID/secret | CI/CD, automation, scripts |
+| Auth Method | When Used | Role Configuration |
+|-------------|-----------|-------------------|
+| User Authentication | Only `--client-id` provided | Roles on your **user account** |
+| Client Credentials | Both `--client-id` and `--client-secret` provided | Roles on the **API client** |
 
 ```bash
+# User Authentication (opens browser for login)
+b2c ods list --client-id xxx
+
 # Client Credentials
 export SFCC_CLIENT_ID=my-client
 export SFCC_CLIENT_SECRET=my-secret
+b2c ods list
 ```
 
 Used by:
 - Code management (`code list`, `code activate`, `code delete`)
 - Job operations (`job run`, `job search`, `job import`, `job export`)
 - Site operations (`sites list`)
 - ODS operations (requires `Sandbox API User` role)
-- SLAS operations (requires `SLAS Organization Administrator` or `Sandbox API User` role)
+- SLAS operations (requires `SLAS Organization Administrator` or `Sandbox API User` role depending on auth method)
 
 ### Basic Auth (WebDAV)
 

docs/cli/ods.md

@@ -12,31 +12,33 @@ These flags are available on all ODS commands:
 
 ## Authentication
 
-ODS commands require an Account Manager API Client with appropriate roles.
+ODS commands require an Account Manager API Client.
 
 ### Required Roles
 
-| Auth Method | Role | Description |
-|-------------|------|-------------|
-| User Authentication | `Sandbox API User` | For interactive/browser-based authentication |
-| Client Credentials | `Sandbox API User` | For automated/service authentication |
+| Auth Method | Role | Configured On |
+|-------------|------|---------------|
+| User Authentication | `Sandbox API User` | Your user account |
+| Client Credentials | `Sandbox API User` | The API client |
+
+**User Authentication**: Used when only `--client-id` is provided. Opens a browser for login. The `Sandbox API User` role must be assigned to your user account in Account Manager.
+
+**Client Credentials**: Used when both `--client-id` and `--client-secret` are provided. The `Sandbox API User` role must be assigned to the API client.
 
 ### Tenant Scope
 
-The API client must have tenant scope configured for the realm(s) you wish to manage. This is configured in Account Manager when setting up the API client.
+The API client must have tenant scope configured for the realm(s) you wish to manage. This is configured in Account Manager under the API client's **Organizations** section.
 
 ### Configuration
 
-Provide credentials via flags or environment variables:
-
 ```bash
+# User Authentication (opens browser)
+b2c ods list --client-id xxx
+
 # Client Credentials
 export SFCC_CLIENT_ID=my-client
 export SFCC_CLIENT_SECRET=my-secret
 b2c ods list
-
-# Or via flags
-b2c ods list --client-id xxx --client-secret yyy
 ```
 
 ---

docs/cli/slas.md

@@ -12,31 +12,33 @@ These flags are available on all SLAS commands:
 
 ## Authentication
 
-SLAS commands require an Account Manager API Client with appropriate roles.
+SLAS commands require an Account Manager API Client.
 
 ### Required Roles
 
-| Auth Method | Role | Description |
-|-------------|------|-------------|
-| User Authentication | `SLAS Organization Administrator` | For interactive/browser-based authentication |
-| Client Credentials | `Sandbox API User` | For automated/service authentication |
+| Auth Method | Role | Configured On |
+|-------------|------|---------------|
+| User Authentication | `SLAS Organization Administrator` | Your user account |
+| Client Credentials | `Sandbox API User` | The API client |
+
+**User Authentication**: Used when only `--client-id` is provided. Opens a browser for login. Roles must be assigned to your user account in Account Manager.
+
+**Client Credentials**: Used when both `--client-id` and `--client-secret` are provided. Roles must be assigned to the API client.
 
 ### Tenant Scope
 
-The API client must have tenant scope configured for the realm/organization you wish to manage. This is configured in Account Manager when setting up the API client.
+The API client must have tenant scope configured for the organization you wish to manage. This is configured in Account Manager under the API client's **Organizations** section.
 
 ### Configuration
 
-Provide credentials via flags or environment variables:
-
 ```bash
+# User Authentication (opens browser)
+b2c slas client list --tenant-id abcd_123 --client-id xxx
+
 # Client Credentials
 export SFCC_CLIENT_ID=my-client
 export SFCC_CLIENT_SECRET=my-secret
 b2c slas client list --tenant-id abcd_123
-
-# Or via flags
-b2c slas client list --tenant-id abcd_123 --client-id xxx --client-secret yyy
 ```
 
 ---

docs/guide/authentication.md

@@ -18,26 +18,51 @@ The CLI uses different authentication mechanisms depending on the operation:
 
 Most CLI operations require an Account Manager API Client. This is configured in the Salesforce Commerce Cloud Account Manager.
 
+### Authentication Methods
+
+The CLI supports two authentication methods:
+
+| Method | When Used | Role Configuration |
+|--------|-----------|-------------------|
+| **User Authentication** | When only `--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** |
+
+**User Authentication** opens a browser for interactive login and uses roles assigned to your user account. This is ideal for development and manual operations.
+
+**Client Credentials** uses the API client's secret for non-interactive authentication. This is ideal for CI/CD pipelines and automation.
+
 ### Creating an API Client
 
 1. Log in to [Account Manager](https://account.demandware.com)
 2. Navigate to **API Client** in the left menu
 3. Click **Add API Client**
 4. Fill in the required fields:
    - **Display Name**: A descriptive name (e.g., "B2C CLI")
-   - **Password**: A strong client secret (save this securely)
+   - **Password**: A strong client secret (save this securely for Client Credentials auth)
 5. Configure the **Token Endpoint Auth Method**:
    - `client_secret_post` for client credentials flow
 6. Set **Access Token Format** to `JWT`
 
 ### Assigning Roles
 
-Under the **Roles** section, add the appropriate roles based on what operations you need:
+Roles grant permission to perform specific operations. Where you configure roles depends on your authentication method:
+
+#### For Client Credentials (roles on API Client)
+
+Under the API Client's **Roles** section, add:
+
+| Role | Operations |
+|------|------------|
+| `Sandbox API User` | ODS management, SLAS client management |
+
+#### For User Authentication (roles on User)
+
+In Account Manager, navigate to your user account and add roles:
 
 | Role | Operations |
 |------|------------|
-| `Sandbox API User` | ODS management, SLAS client management (client credentials) |
-| `SLAS Organization Administrator` | SLAS client management (user authentication) |
+| `Sandbox API User` | ODS management |
+| `SLAS Organization Administrator` | SLAS client management |
 
 ### Configuring Scopes