Improved API Security

25A introduces an enhanced API security control feature that classifies store endpoint calls as either implicit (originating from commerce applications) or explicit (originating from external integrations). This feature provides improved traceability of external API calls and allows for flexible enforcement of access control on explicit calls using token-based validation.

Key Features

X-API-Mode Response Header

• X-API-Mode: Implicit - Response Header set automatically for endpoint requests originating from internal commerce applications.
• X-API-Mode: Explicit - Response Header set automatically for endpoint requests originating from external integrations.

Token-Based Access Control

• Access-Token Request Header (Required): To access any secured endpoints once token-based access control is enabled, requests must include the access-token header with a valid token value.
• Restricted Endpoints: Once token-based access control is enabled, only endpoints or endpoint contexts defined in the token configuration will accept requests with a valid access-token. Requests to any other endpoints will be denied with a 403 Forbidden response.
• Token Configuration: Configure secret tokens and their associated API endpoints by submitting a JSON payload via the endpoint /ccadmin/v1/whitelist/tokens

Token Configuration Format

The system validates tokens using a JSON configuration that associates tokens with allowed API endpoints.

Explicit / Fully Qualified Endpoint:

Here, the configured token is valid only for /ccstore/v1/products, /ccstore/v1/sites and /ccapp/v1/login and not for any other endpoint.

{

   "tokens":[

      {

         "api":[

            "/ccstore/v1/products",

            "/ccstore/v1/sites"

         ],

         "token":"7c2dfc6f8336b8e89628be42f74bccefb3204d9c1842a2983e6f54ae413f93cd"

      },

      {

         "api":[

            "/ccapp/v1/login"

         ],

         "token":"123455b8e89628be42f74bccefb3204d9c1842a2983e6f54ae413f93cd"

      }

   ]

}

Context-Based / Base Path Endpoint:

Specify a base path (like /ccstore/v1), which automatically grants access to all endpoints under that path

{

   "api":[

      "/ccstore/v1"

   ],

   "token":"123455b8e89628be42f74bccefb3204d9c1842a2983e6f54ae413f93cd"

}

This feature offers clear traceability of external API calls and provides flexibility to enforce access control for API calls classified as explicit.

Steps to Enable

This capability is disabled by default and can be enabled upon request. To enable it, please log a Service Request (SR) with Oracle Support.

Tips And Considerations

• Requests to any secured endpoints must include the access-tokenheader with a valid token from the configured list.
• Requests to endpoints not listed in the token configuration will not be authorised and will fail once token-based access control is enabled.
• This means enabling token-based access control effectively limits external API access strictly to the configured endpoints and tokens.
• When making Store API calls from Server-Side Extensions, use the base URL of the store supplemented by the environment variable process.env.OCC_APP_SERVER. This ensures that API requests are honoured and not rejected as explicit API calls, which would require a token