API Clients Configuration

The Alokai SFCC SDK supports the use of both SCAPI and OCAPI, either individually or in parallel. SCAPI is used by default for endpoints which it supports. Each endpoint can be switched to OCAPI using the ocapiEndpoints configuration object. It is a typed map of boolean values, with the keys being all available API endpoints the integration provides. If the required configuration values for one of the clients are not provided, that client will not be used.

SCAPI

In order to use SCAPI, the following configuration values are required:

scapiClientId

This is the ID of the API client to use for all SCAPI requests. It is created in Account Manager

slasClientId

This is the SLAS client ID that will be used for authentication. It can be created by following the process described in the platform documentation. Both public and private clients are supported (see slasClientSecret).

Note: If an OCAPI key is in use, it's recommended to have this be the same (the client ID value can be set manually during creation). This will allow for interoperability between SCAPI and OCAPI on persistent objects such as carts and baskets that are owned by guests, since it would allow both API families to share the same JWT for authentication, and by extension - the same guest customer ID.

For scopes, the following values will cover the full integration functionality:

sfcc.shopper-baskets-orders
sfcc.shopper-baskets-orders.rw
sfcc.shopper-categories
sfcc.shopper-customers.login
sfcc.shopper-customers.register
sfcc.shopper-myaccount
sfcc.shopper-myaccount.addresses
sfcc.shopper-myaccount.addresses.rw
sfcc.shopper-myaccount.baskets
sfcc.shopper-myaccount.orders
sfcc.shopper-myaccount.paymentinstruments
sfcc.shopper-myaccount.paymentinstruments.rw
sfcc.shopper-myaccount.productlists
sfcc.shopper-myaccount.productlists.rw
sfcc.shopper-myaccount.rw
sfcc.shopper-product-search
sfcc.shopper-productlists
sfcc.shopper-products
sfcc.shopper-promotions
sfcc.shopper-stores

For Redirect URI, the /sfcc/slas/signIn/redirect path exposed by the middleware needs to be provided.

In the example in quick-start, the value would be http://localhost:8181/sfcc/slas/signIn/redirect

For Callback URL, the /sfcc/slas/resetPassword/callback path exposed by the middleware needs to be provided.

This URL needs to be publicly accessible, so using localhost will not work. During development, a solution such as ngrok or Cloudflare Tunnel can be used to expose the url.

organizationId

This is an identifier for the realm and the environment that is used. It is described in the platform documentation

shortCode

This is an identifier for the realm that is used. It is described in the platform documentation

The following can be optionally provided:

slasClientSecret

This is only required for private SLAS clients. It is generated when the client is created and can only be read at this time. If this secret value gets lost, it needs to be reset by switching the client to public, and then converting it to private again, that way a new secret will be generated.

If provided, the integration will use the private authentication flow. If not provided, the integration will use the public authentication flow.

commerceApiVersion

This is the version that is used in the API URLs. Currently only v1 is available and is the default value. This setting currently exists just for future-proofing.

OCAPI

In order to use OCAPI, the following configuration values are required:

origin

This is the base URL for all API calls. Since OCAPI is instance-specific, this needs to maych the public URL of the instance, e.g. https://development-realm-client.demandware.net for PIG instances and https://realm-001.dx.commercecloud.salesforce.com for sandboxes.

ocapiClientId

This is the ID of the API client to use for all SCAPI requests. It is created in Account Manager

ocapiClientSecret

This is the client's password from account manager. OCAPI is split into two APIs, SHOP for client-facing functionalities and DATA for admin functionalities. The integration only uses SHOP endpoints which normally don't require a secret, but despite that it needs to do an admin authentication since some of the endpoints require it.

ocapiVersion

This is the version that will be included in the API URLs. The integration is built on 23_2 but future versions should work as well, barring breaking changes. Since OCAPI has been supplanted by SCAPI, these are unlikely to happen. Versioning is described in the platform documentation

Configuration

In order to allow the client access to the various endpoints, a permissions configuration needs to be added in the BM of the instance that is used. The process is described in the platform documentation.

An easy starting point for non-production environments could be to provide access to all resources:

{
  "_v": "23.2",
  "clients": [
    {
      "client_id": "<client-id>",
      "resources": [
        {
          "resource_id": "/**",
          "methods": [
            "get",
            "put",
            "post",
            "patch",
            "delete"
          ],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        }
      ]
    }
  ]
}

For production environments, only the required paths should be listed. The integration can currently execute the following requests:

GET /categories/*
GET /product_search
GET /products/*
POST /customers
GET /customers/*
POST /customers/auth
DELETE /customers/auth
POST /customers/password/actions/reset
POST /customers/password/actions/create_reset_token
GET /customers/*/orders
GET /customers/*/baskets
PATCH /customers/*
PUT /customers/*/password
POST /customers/*/addresses
PATCH /customers//addresses/
DELETE /customers//addresses/
POST /customers/*/payment_instruments
DELETE /customers//payment_instruments/
GET /customers/*/product_lists
POST /customers/*/product_lists
POST /customers//product_lists//items
DELETE /customers//product_lists//items/*
PUT /baskets/*/billing_address
PUT /baskets/*/customer
POST /baskets/*/items
PATCH /baskets//items/
DELETE /baskets//items/
POST /baskets/*/gift_certificates
PATCH /baskets//gift_certificates/
DELETE /baskets//gift_certificates/
POST /baskets/*/coupons
DELETE /baskets//coupons/
POST /baskets/*/payment_instruments
PATCH /baskets//payment_instruments/
DELETE /baskets//payment_instruments/
POST /baskets/*/shipments
PATCH /baskets//shipments/
DELETE /baskets//shipments/
GET /baskets//shipments//shipping_methods
POST /orders
POST /order_search
GET /stores
GET /stores/*

The full configuration for all of them could look like this:

{
  "_v": "23.2",
  "clients": [
    {
      "client_id": "<client-id>",
      "resources": [
        {
            "resource_id": "/categories/*",
            "methods": ["get"],
            "read_attributes": "(**)"
        },
        {
            "resource_id": "/product_search",
            "methods": ["get"],
            "read_attributes": "(**)"
        },
        {
            "resource_id": "/products/*",
            "methods": ["get"],
            "read_attributes": "(**)"
        },
        {
            "resource_id": "/customers",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*",
            "methods": ["get", "patch"],
            "read_attributes": "(**)"
        },
        {
            "resource_id": "/customers/auth",
            "methods": ["post", "delete"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/password/actions/reset",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/password/actions/create_reset_token",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/orders",
            "methods": ["get"],
            "read_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/baskets",
            "methods": ["get"],
            "read_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/password",
            "methods": ["put"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/addresses",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/addresses/*",
            "methods": ["patch", "delete"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/payment_instruments",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/payment_instruments/*",
            "methods": ["delete"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/product_lists",
            "methods": ["get", "post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/product_lists/*/items",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/customers/*/product_lists/*/items/*",
            "methods": ["delete"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/billing_address",
            "methods": ["put"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/customer",
            "methods": ["put"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/items",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/items/*",
            "methods": ["patch", "delete"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/gift_certificates",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/gift_certificates/*",
            "methods": ["patch", "delete"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/coupons",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/coupons/*",
            "methods": ["delete"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/payment_instruments",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/payment_instruments/*",
            "methods": ["patch", "delete"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/shipments",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/shipments/*",
            "methods": ["patch", "delete"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/baskets/*/shipments/*/shipping_methods",
            "methods": ["get"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/orders",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/order_search",
            "methods": ["post"],
            "read_attributes": "(**)",
            "write_attributes": "(**)"
        },
        {
            "resource_id": "/stores",
            "methods": ["get"],
            "read_attributes": "(**)"
        },
        {
            "resource_id": "/stores/*",
            "methods": ["get"],
            "read_attributes": "(**)"
        }
      ]
    }
  ]
}

It it recommended to only whitelist the resources that will actually be used through OCAPI, as well as keep in mind any PCI or PII restrictions on field visibility as the example above allows all fields to be viewed and edited.