How to authenticate API and authoritarian Sitecore Discover APIs?

Please note that if you have a subdomain, there is no need for any authorization or authentication, and you can skip this section. When making API calls, simply use the subdomain host URL in the format <nickname>.rfk.<customerdomain.com>. This subdomain host URL provides adequate authentication and authorization, unlike the non-subdomain host URL format, which is api.rfksrv.com.

In case you don't have a subdomain, it is necessary to authenticate and authorize yourself before accessing the Discover REST APIs. Authentication is the process of confirming your validity as a user to Discover, while authorization ensures that you possess the necessary permissions to access the desired API. By implementing authentication and authorization, Discover ensures you and your customers a secure and protected experience.

Now we have two ways to authenticate: the API key method or the access token method. For authorization, you can make use of scopes.

The authentication and authorization process for the Discover API follows these steps:

1. Obtain an API key with the necessary scopes. Typically, this step is performed only once.

2. If necessary, generate an access token and refresh token. This step must be repeated whenever a token expires.

3. Include the API key or access token in the headers of all your requests. This step is required for every request you make.

Detailed descriptions of the API key, access token, and refresh token are provided in the following sections.

API Key:

The Discover API key serves as a unique and secure 52-character secret code, which is provided by your Sitecore account manager upon initial registration. API keys are perpetual and do not have an expiration date.

Example of an API key: 01-90c83624-12f708fa77a1e96a25c4a2afd0f28a4c23ff5252

It's important to note that API keys cannot be generated independently; Sitecore generates them for you and makes them available in the Customer Engagement Console (CEC). To access your API key, simply navigate to the CEC, click on Developer Resources, and then API Access.

Keep in mind: For security reasons, we highly recommend using API Keys exclusively in secure environments, such as your server. Utilizing API keys in non-secure clients like browsers could pose potential security risks.

To access the Discover API, you can leverage an API key to generate an access token. Afterward, include either the API key or the access token in the request header to interact with the Discover API effectively.

API Key Scopes:

Every API key is associated with specific scopes that determine the accessibility of REST APIs. These scopes dictate which APIs you can access and which ones you are restricted from. Your account manager can assign the necessary scopes to your API key based on the APIs you intend to utilize.

An API key can possess one, several, or all of the following scopes:

1. search-rec: This scope grants authorization to utilize the Discover search and recommendation API.

2. event: With this scope, you are authorized to make calls to the Discover events API.

3. feed: This scope, in conjunction with services, allows you to access the Discover incremental feed API.

4. services: Along with the feed scope, this authorization enables you to call the Discover incremental feed API.

It is crucial to ensure that the API key you employ matches the API you are invoking. Failure to do so will result in an error. For instance, if you attempt to access the Event API using an API key that only possesses the search-rec scope, an HTTP 4XX error will be returned.

Access Token and Refresh Token:

An access token serves as a temporary code for authenticating an API request, while a refresh token is a temporary code used to obtain a new access token.

Please keep in mind: When making calls from non-secure clients like browsers, it is recommended to use tokens instead of sending an API key.

To begin, initiate a request from your server to the Discover authentication endpoint using the API key. In the response, you will receive an access token and a refresh token. Once the access token expires, utilize the refresh token to obtain a new access token. Similarly, if the refresh token expires, you can obtain a fresh access token by using the API key.

Access tokens and refresh tokens have limited validity. By default, access tokens are valid for 1 day, and refresh tokens are valid for 1 week. While you can reduce the validity period, extending it beyond the default duration is not possible.

You have the capability to generate access tokens and refresh tokens, and it is also feasible to include an access token in the request header.

Access Token Scopes:

Access tokens and refresh tokens inherit the scopes assigned to the API Key. For example, if an API key with search-rec and event scopes is utilized to generate an access token, the resulting access token will allow you to make API calls to the search and recommendation APIs and event APIs. However, it will not provide access to the incremental feed API.