# Authentication and Authorization

To make sure that the setup is complete, 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](https://developer.salesforce.com/docs/commerce/commerce-api/references/custom-apis?meta=getEndpoints) 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](https://developer.salesforce.com/docs/commerce/commerce-api/references/custom-apis?meta=Summary).

## Secure Endpoints

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](/docs/commerce/b2c-commerce/guide/slas.md) to obtain tokens.
- `AmOAuth2`: For SCAPI Admin APIs to be used with backoffice apps. Use [Account Manager](/docs/commerce/b2c-commerce/guide/authorization-for-admin-apis.md) 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:

```yaml
components:
  securitySchemes:
    ShopperToken: {}
    AmOAuth2:
      type: oauth2

# 👇 A global scheme applies to all operations in this file.
security:
  - AmOAuth2: ["c_loyalty_rw"]

paths:
  /customer:
    get:
      operationId: getLoyaltyInfo
      parameters:
        - in: query
          name: siteId
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        200:
          description: OK
      # 👇 An operation scheme applies only to this operation and takes precedence over the global scheme.
      security:
        - ShopperToken: ["c_loyalty"]
```

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`.

## Request Endpoints

### ShopperLogin

Scopes for `ShopperLogin` can be assigned to a client in the [SLAS Admin UI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.md). For example:

![Custom API SLAS scope configuration and permissions](https://a.sfdcstatic.com/developer-website/sfdocs/commerce-cloud/media/commerce-api/custom-api-slas-scopes.png)

To obtain a SLAS token, follow the steps in the [Shopper Login](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.md) overview.

### AmOAuth2

Custom scopes for `AmOAuth2` can be assigned to a client in [Account Manager](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.md). For example:

![Account Manager OAuth2 scopes configuration for Custom APIs](https://a.sfdcstatic.com/developer-website/sfdocs/commerce-cloud/media/commerce-api/custom-api-amoauth2-scopes.png)

To obtain an Account Manager token follow the steps in the [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.md) guide.

Unauthorized requests receive a `401 Unauthorized` response.

## Complete Security Scheme Definition

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:

```yaml
components:
  securitySchemes:
    ShopperToken:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://my-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize
          tokenUrl: https://my-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
          scopes:
            c_my-scopes: description of my-scopes
        clientCredentials:
          tokenUrl: https://my-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
          scopes:
            c_my-scopes: description of my-scopes
    AmOAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize
          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
          scopes:
            c_my-scopes: description of my-scopes
        clientCredentials:
          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
          scopes:
            c_my-scopes: description of my-scopes
```