Authentication and Authorization

To ensure a complete setup, you must provide a scope for custom code execution and also a scope for API administration:

• Functional scopes (c_ prefix): These custom scopes authorize the execution of your specific business logic. They handle the request authorization for the code itself.
• Diagnostic/Administrative Scope (sfcc.custom-apis and sfcc.custom-apis.rw): This scope is required to access the DX API. While your c_ scope runs your custom code, the sfcc.custom-apis scope provides the necessary visibility into the registration status and scaffolding of the Custom API framework.

Custom APIs must be secured by a security scheme which includes exactly one functional scope. Custom API clients must obtain a token with the required scope. To secure your custom endpoints and make authorized requests to them, complete the following steps:

1. Choose a security scheme and custom scope for the endpoint.
2. Update your API client to include the custom scope in tokens.

The Custom APIs DX endpoint uses an Account Manager OAuth 2.0 bearer token for authentication and you must specify one of the following scopes to access this API endpoint:

sfcc.custom-apis: Provides read-only access. sfcc.custom-apis.rw: Provides read-write acc

For additional Custom API DX details, see Custom APIs Authentication and Authorization.

Your Custom API endpoints must be associated with a security scheme in the API contract.

• ShopperToken: For Shopper APIs and storefront use cases. Use Shopper Login and API Access to obtain tokens.
• AmOAuth2: For SCAPI Admin APIs to be used with backoffice apps. Use Account Manager to obtain tokens.

Association is either per operation or global, with the operation scheme taking precedence. The schemes are the same as those used for non-custom B2C Commerce APIs (SCAPI).

The scheme must set exactly one custom scope.

Schemes used in the contract must be defined in the components section, for example:

Custom scopes must meet the following requirements:

• The name must begin with c_.
• The name must not contain characters other than alphanumeric, period, hyphen and underscore.
• The name must not be more than 25 characters.

Endpoints without correct scheme or scope assignments are not registered.

You can review registration errors by searching in the Log Center for messages with a category that includes CustomApiRegistry.

Scopes for ShopperLogin can be assigned to a client in the SLAS Admin UI. For example:

To obtain a SLAS token, follow the steps in the Shopper Login overview.

Custom scopes for AmOAuth2 can be assigned to a client in Account Manager. For example:

To obtain an Account Manager token follow the steps in the Authorization for Admin APIs guide.

Unauthorized requests receive a 401 Unauthorized response.

While endpoint registration does not require the complete definition of the security schemes, it can be useful to have a complete and valid scheme to enable the creation of documentation, tests and code stubs, and mock requests. The following code provides a complete example: