Authentication and Authorization

Custom APIs must be secured by a security scheme which includes exactly one custom scope. To access Custom APIs, clients must obtain a token with the required scope.

To secure your 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.

Endpoints must be associated with a security scheme in the API contract:

Association is either per operation or global, with the operation scheme taking precedence. The schemes are the same as those used for system APIs.

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:

Associated diagram

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:

Associated diagram

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: