API authentication and authorization
If you have a subdomain , you do not need to do any authorization or authentication, and you can ignore this section. You make API calls to the subdomain host URL, which looks like <nickname>.rfk.<customerdomain.com>, as opposed to a non-subdomain host URL that looks like api.rfksrv.com. Using the subdomain host is sufficient authentication and authorization.
If you do not have a subdomain, you must authenticate and authorize yourself before you can access Discover REST APIs. When you authenticate, you tell Discover that you are a valid user. When you authorize, you tell Discover that you have sufficient rights to access the API you want to call. Together, authentication and authorization make sure that you and your customers have a safe and secure experience.
You can authenticate using the API key method or the access token method. You can authorize using scopes.
The Discover API authentication and authorization process flows like this:
-
Get an API key with the required scopes. Usually, you only have to do this once.
-
If required, generate an access token and a refresh token. You must do this each time a token expires.
-
Pass the API key or access token in all request headers. You must do this for every request you make.
The following sections describe the API key, access token, and refresh token in detail.
API key
The Discover API key is a unique and secure 52-character secret code that you get from your Sitecore account manager when you first register. API keys do not expire.
This is a sample API key: 01-90c83624-12f708fa77a1e96a25c4a2afd0f28a4c23ff5252
You cannot generate an API key on your own. Sitecore generates it for you and makes it available in the Customer Engagement Console. You can view your API key at any time by going to the CEC, clicking on Developer Resources, and then API Access.
We strongly recommend using API Keys only in a secure environment like your server. Using API keys in a non-secure client like a browser can lead to security issues.
You can use an API key to generate an access token. Then, add an API key or an access token to a request header to access Discover API.
API key scopes
All API keys have scopes assigned to them. This scope determines which REST APIs you can access and which you cannot. Depending on the APIs that you want to call, your account manager can assign the required scopes to your API key.
An API key can have one, some, or all of the following scopes:
-
search-rec- this scope authorizes you to use the Discover search and recommendation API. -
event- this scope authorizes you to call the Discover events API. -
feed- this scope, along withservices, authorizes you to call the Discover incremental feed API. -
services- this scope, along withfeed, authorizes you to call the Discover incremental feed API.
The API key you use must match the API you call. If not, you get an error. For example, if you call the Event API with an API key that only has the search-rec scope, you get an HTTP 4XX error.
Access token and refresh token
An access token is a temporary code that you can use to authenticate an API request. A refresh token is a temporary code that you can use to get a new access token.
Use tokens when you make calls from a non-secure client, like a browser, for example, where it is not safe to send an API key across.
First, use the API key to make a call from your server to the Discover authentication endpoint. In the response, you get an access token and a refresh token. When the access token expires, use the refresh token to get a new access token. When the refresh token expires, use the API key to get a new access token.
Access tokens and refresh tokens have limited validity. The default is 1 day for an access token and 1 week for a refresh token. You can change the validity to shorter than the default amounts, but not more
You can generate access tokens and refresh tokens, and you can add an access token to a request header.
Access token scopes
Access tokens and refresh tokens inherit scopes from the API Key. For example, assume you used an API key with the search-rec and event scopes to generate an access token. You can use the access token that you generate from this API key to call the search and recommendation APIs and event APIs, but not the incremental feed API.