Authentication

You'll need to authenticate your requests to access any of the endpoints in the BetterCommerce API. In this guide, we'll look at how authentication works. BetterCommerce offers two ways to authenticate your API requests: Basic authentication and OAuth2 with a token — OAuth2 is the recommended way.

The BetterCommerce APIs are REST based API.
As of now, there is no support for GraphQL but in due course of time, the support for GraphQL will also be provided based on customer demands.
The APIs are hosted in Microsoft Azure Infrastructure.

OAuth2 bearer token

The BetterCommerce APIs provide authentication support based on OAUTH2.

BC API supports OAUTH2 bearer token mechanism which can generated dynamically using the AUTH APIs.
The bearer token can be simply generated by making a the api call to AUTH API mentioned above and passing the api client id & shared secret.

Authentication API

The token has a predefined expiry of 24 hours, after which a new token has to be requested using the refresh_token.

Example request to fetch bearer token

curl https://auth.omnicx.com/oAuth/Token \
  -H "Content-type: application/x-www-form-urlencoded" \
  -d "client_id=<<client_id>>&client_secret=<<shared_secret>>&grant_type=client_credentials"

Authentication token response

{
    "access_token": "<<access_token>>",
    "token_type": "bearer",
    "expires_in": 3599,
    "refresh_token": "<<refresh_token>>"
}

Sample API requests using the Bearer Token

Example request with bearer token

curl <api_url>/api/v2/catalog/brand/all \
  -H "Authorization: Bearer {token}"

Always keep your token safe and reset it if you suspect it has been compromised.

Additional Custom Headers

The following additional custom headers can be passed to ALL the API calls. These data inputs are typically useful to localize different elements of the user experience and for the sake of simplicity provided as headers within the API call rather than an input param for each method.

Key	Description	Value Source
Currency	Currency selected by the user or inherited from the Microsite (if enabled). This enables the API to return the pricing information in the required currency.	There are multiple sources of this – user selected currency, default currency for the site / microsite (if enabled). Possible Values – GBP, EUR, USD, AUD, etc. (3 letter currency codes)
Language	Should be passed with Lang code for the user. This enables the API to return the localized content for the specific language.	User selected language or default language setup at site / microsite (if enabled) level. Possible values - en, de, fr, etc.
Country	The country value is used to bring the default pricelist, shipping method enabled at the country level. By default, the store’s default country code is set, however this can be changed in the storefront to be based on user’s access point determined using their IP address.	The default value is picked based on store settings but can be changed. Possible value – DE, GB, RU, US, ROW (Rest of the world)
UserId	If the user is logged in, then we should be passing the UserId (GUID) for the logged-in user as a custom header to each API request	Passed up from the user session.
Email	If the user is logged in, then we should be passing the Email for the logged-in user as a custom header to each API request	Passed up from the user session.