Merge pull request #461 from andimov/fix-accs-api

keharper · web-flow · commit 63dc33ad93ac · 2025-07-11T12:41:56.000-05:00
Update  authentication section to clarify OAuth Authorization  flows
diff --git a/src/data/navigation/sections/rest.js b/src/data/navigation/sections/rest.js
@@ -27,14 +27,14 @@ module.exports = [
                 title: "Introduction",
                 path: "/rest/authentication/"
             },
+            {
+                title: "Server-to-server authentication",
+                path: "/rest/authentication/server-to-server.md",
+            },
             {
                 title: "User authentication",
                 path: "/rest/authentication/user.md",
             },
-            {
-                title: "Server-to-server authentication",
-                path: "/rest/authentication/server-to-server.md",
-            }
         ],
     },
   {
diff --git a/src/pages/rest/authentication/index.md b/src/pages/rest/authentication/index.md
@@ -1,158 +1,79 @@
 ---
 title: Authentication in Adobe Commerce as a Cloud Service
-description: Generate the IMS access token for admin user.
+description: Learn about REST API authentication in Adobe Commerce as a Cloud Service.
 edition: saas
 keywords:
   - REST
   - Integration
---- 
- 
-# Authentication in Adobe Commerce as a Cloud Service
-
-In Adobe Commerce as a Cloud Service (SaaS), you must use Adobe's Identity Management Service (IMS) for admin authentication. The traditional admin token generation method is not supported in SaaS environments. Instead, you must obtain an IMS admin token through OAuth authentication.
-
-This authentication method ensures that all API calls are performed within the context of the authenticated admin user's permissions, as defined in the ACCS.
-
-<InlineAlert variant="note" slots="text"/>
-
-See [Authentication](../../get-started/authentication/index.md) in the _Get Started_ guide for information about the authentication methods available on other versions of Adobe Commerce.
-
-## Authentication Options for Adobe Commerce as a Cloud Service
-
-Adobe Commerce as a Cloud Service (ACCS) supports two primary authentication methods for admin-level API access:
-
-- **User authentication (IMS)** - Use this method when you need to authenticate on behalf of a specific admin user with user-specific permissions. This page covers the user authentication flow.
-
-- **Server-to-server integration** - Use this method for automated system-to-system communication without user intervention. For detailed instructions on setting up server-to-server integration, see [Create server-to-server integration](server-to-server.md).
-
-## Security best practices
-
-- Store tokens securely using encryption at rest.
-- Implement proper token rotation procedures.
-- Monitor token expiration and implement automatic refresh.
-- Use HTTPS for all authentication requests.
-- Validate state parameters to prevent CSRF attacks.
-
-## Generate an IMS access token
-
-Before implementing IMS authentication, ensure you have:
-
-- An active Adobe Commerce as a Cloud Service license.
-- Access to Adobe Developer Console for creating OAuth credentials.
-- A configured redirect URI where users will return after authentication.
-- A secure environment for token handling.
-
-### Step 1: Generate IMS credentials
-
-1. Navigate to Adobe Developer Console.
-1. Create or select a project that will house your authentication credentials.
-1. Add the **Adobe Commerce with Adobe ID** API to your project.
-1. Select your preferred OAuth 2 authentication type:
-   - **Web App**: For applications with a backend server that can securely store client secrets
-   - **Single-Page App (SPA)**: For browser-based JavaScript applications
-   - **Native App**: For device-native applications (iOS, Android, desktop)
-1. Configure the allowed redirect URIs.
-1. Copy the client ID and client secret.
-1. Securely save your credentials.
-
-### Step 2: Implement the authorization flow and response
-
-To authenticate a user and obtain an authorization code, follow these steps:
-
-1. Create an authorization URL to initiate the authentication process. The URL has the following format:
-
-   ```http
-   https://ims-na1.adobelogin.com/ims/authorize/v2?client_id={{client_id}}&redirect_uri={{redirect_uri}}&scope={{scopes}}&state=something&response_type=code
-   ```
-
-  Replace the placeholders with your values:
-  
-  - `{{client_id}}`: Your IMS client ID
-  - `{{redirect_uri}}`: Your configured redirect URI
-  - `{{scopes}}`: A comma-separated list of required scopes, such as `AdobeID,openid,email,profile,additional_info.roles,additional_info.projectedProductContext`
-
-1. Handle the authorization response. When the user completes authentication through Adobe's login interface, the browser redirects to your `redirect_uri`. The authorization code is included in URL parameters:
-
-  `?code={{auth_code}}&state=something`
-  
-  Extract the authorization code and verify the state parameter
-
-### Step 3: Exchange the authorization code for an access token
-
-Make a POST request to exchange the authorization code for an access token:
+---
 
-**Endpoint:**
+# REST Authentication in Adobe Commerce as a Cloud Service
 
-`POST https://ims-na1.adobelogin.com/ims/token/v3`
+Adobe Commerce as a Cloud Service REST API authentication is handled through Adobe's Identity Management System (IMS) through standardized OAuth 2 protocols. This authentication system supports both interactive user-based workflows and automated server-to-server integrations, ensuring secure and appropriate access for different use cases. The traditional admin and integration token generation methods is not supported in SaaS environments. Instead, you must obtain an IMS admin token through OAuth authentication.
 
-**Headers:**
+The following types of authentication are available for Adobe Commerce as a Cloud Service REST APIs:
 
-```text
-Authorization: Basic {{base64(client_id:client_secret)}}
-Content-Type: application/x-www-form-urlencoded
-```
+- [Server-to-server authentication](#server-to-server-authentication) - Choose this flow for automated, system-to-system integrations that do not require user interaction, such as background jobs, integrations, and scripts.
 
-**Payload:**
+- [User authentication](#user-authentication) - Choose this flow when API operations must be performed by an admin user according to their permissions, such as when actions must be attributed to a specific admin user.
 
-```text
-code={{auth_code}}&grant_type=authorization_code
-```
+See [Authentication](../../get-started/authentication/index.md) in the _Get Started_ guide for information about the authentication methods available on other versions of Adobe Commerce.
 
-**Response:**
+## Server-to-server authentication
 
-```json
-{
-    "access_token": "{ACCESS_TOKEN}",
-    "refresh_token": "{REFRESH_TOKEN}",
-    "sub": "A0BC123D4CD449CA0A494133@a12b34cd5b5b7e0e0a494004",
-    "id_token": "{ID_TOKEN}",
-    "token_type": "bearer",
-    "expires_in": 86399
-}
-```
+Server-to-server authentication enables automated systems to interact with Commerce APIs without user intervention. This method uses technical account credentials to obtain access tokens directly, making it perfect for background processes, scheduled tasks, and system integrations that need to operate independently.
 
-### Step 4: Use the access token
+Key benefits of this approach include:
 
-Use the access token in the Authorization header for all Commerce REST API calls, such as retrieving a list of products.
+- Non-interactive authentication for automated processes
+- Obtain a new access token as needed using client credentials
+- Ideal for headless and backend integrations
+- Support for system-wide permissions and access control
 
-**Endpoint:**
+For detailed steps, see the [server-to-server Authentication Guide](./server-to-server.md).
 
-`GET https://<server>.api.commerce.adobe.com/<tenant-id>/v1/products`
+## User authentication
 
-**Headers:**
+The user authentication flow provides a secure, OAuth-based workflow where users authenticate through Adobe IMS, ensuring credentials are never directly handled by your application.
 
-```text
-Authorization: Bearer {ACCESS_TOKEN}
-```
+Key benefits of this approach include:
 
-## Token refresh
+- Direct integration with Adobe's secure authentication interface
+- Automatic handling of user permissions based on Adobe Commerce Admin role
+- Support for interactive workflows in admin applications
+- Token refresh capabilities for extended sessions
+- Compliance with OAuth 2 security standards
 
-Access tokens expire after a certain period (typically 24 hours). Use the refresh token to obtain a new access token:
+For detailed steps, see the [User Authentication Guide](./user.md).
 
-**Endpoint:**
+## Getting started
 
-`POST https://ims-na1.adobelogin.com/ims/token/v3`
+The following concepts apply to both authentication flows and are important for successful integration:
 
-**Headers:**
+- Prerequisites:
+  - Adobe Commerce as a Cloud Service license
+  - Adobe Developer Console access
+  - Understanding of OAuth 2
+- Environment preparation:
+  - Development environment
+  - Adobe Developer Console project configuration
+  - API testing tools
 
-```text
-Authorization: Basic {{base64(client_id:client_secret)}}
-Content-Type: application/x-www-form-urlencoded
-```
+## Access tokens
 
-**Payload:**
+- Use the bearer token type for API authorization
+- Include your access token in the Authorization header of REST API requests
+- Familiarize yourself with token lifecycle management and renewal processes
+- Review security considerations and best practices for token storage
 
-```json
-grant_type=refresh_token&refresh_token={{refresh_token}}
-```
+## Scopes
 
-**Response:**
+The following permission scopes are required for Adobe Commerce as a Cloud Service REST API access:
 
-```json
-{
-    "access_token": "{ACCESS_TOKEN}",
-    "refresh_token": "{REFRESH_TOKEN}",
-    "expires_in": 86399,
-    "token_type": "bearer"
-}
-```
+- `AdobeID`
+- `openid`
+- `email`
+- `profile`
+- `additional_info.roles`
+- `additional_info.projectedProductContext`
+- `commerce.accs`
diff --git a/src/pages/rest/authentication/server-to-server.md b/src/pages/rest/authentication/server-to-server.md
@@ -1,20 +1,19 @@
 ---
-title: Create server-to-server integration
+title: Server-to-server Authentication
 description: Learn how to set up OAuth server-to-server authentication for Adobe Commerce as a Cloud Service REST API
 edition: saas
 keywords:
   - REST
   - Integration
 --- 
  
-# Create server-to-server integration
+# Server-to-server Authentication
 
-This guide provides practical steps for implementing server-to-server integration with Adobe Commerce as a Cloud Service REST APIs using OAuth server-to-server authentication. This type of integration enables automated system-to-system communication without user intervention, which is ideal for the following use cases:
+This guide provides practical steps for implementing integration with Adobe Commerce as a Cloud Service REST APIs using OAuth 2 server-to-server authentication. This type of integration enables automated communication without user intervention, which is ideal for the following use cases:
 
 - Background processes and automated tasks
 - Data synchronization services
 - Automated reporting systems
-- Microservices architecture integration
 
 ## Prerequisites
 
@@ -53,7 +52,7 @@ Use the following steps to implement server-to-server integration with Adobe Com
 
 ### Step 2: Implement token generation
 
-To authenticate with the Adobe Commerce as a Cloud Service REST APIs, you need to generate an IMS access token using your client credentials. This token is used to authorize API requests.
+To authenticate with the Adobe Commerce as a Cloud Service REST APIs, you need to generate an IMS access token using your client credentials. This token is used to authorize API requests. **Be sure to include the `commerce.accs` scope.**
 
 ```javascript
 // tokenManager.js
@@ -89,7 +88,7 @@ class TokenManager {
           client_id: process.env.IMS_CLIENT_ID,
           client_secret: process.env.IMS_CLIENT_SECRET,
           grant_type: 'client_credentials',
-          scope: 'openid,AdobeID,email,profile,additional_info.roles,additional_info.projectedProductContext'  // required scopes
+          scope: 'openid,AdobeID,email,profile,additional_info.roles,additional_info.projectedProductContext,commerce.accs'  // required scopes
         })
       });
 
@@ -168,9 +167,9 @@ class ACCSApiClient {
 module.exports = ACCSApiClient;
 ```
 
-### Step 4: Usage example
+### Usage example
 
-The following example implementation demonstrates how to use the API client.
+Here is a real-world example of making an authenticated API request after obtaining an access token:
 
 ```javascript
 // example-usage.js
@@ -198,7 +197,7 @@ main();
 
 ## Best practices
 
-The following best practices help ensure your server-to-server integration is secure, efficient, and maintainable.
+The following best practices tips help ensure your server-to-server integration is secure, efficient, and maintainable.
 
 ### Security
 
@@ -220,7 +219,7 @@ The following best practices help ensure your server-to-server integration is se
 
 ## Alternative implementations
 
-The following example shows how to implement server-to-server integration using Python.
+The following example shows how to implement server-to-server integration using Python. **Be sure to include the `commerce.accs` scope.**
 
 ```python
 import os
@@ -256,7 +255,7 @@ class ACCSTokenManager:
             'client_id': self.client_id,
             'client_secret': self.client_secret,
             'grant_type': 'client_credentials',
-            'scope': 'openid,AdobeID,email,profile,additional_info.roles,additional_info.projectedProductContext'
+            'scope': 'openid,AdobeID,email,profile,additional_info.roles,additional_info.projectedProductContext,commerce.accs'
         }
         
         try:
@@ -325,5 +324,5 @@ If you encounter issues during implementation, consider the following troublesho
 ### Token Generation Fails
 
   - Verify your client ID and secret are valid
-  - Check that your OAuth Server-to-Server credentials are properly configured
+  - Check that your OAuth server-to-server credentials are properly configured
   - Ensure you're using the correct IMS endpoint
diff --git a/src/pages/rest/authentication/user.md b/src/pages/rest/authentication/user.md
