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 you can get on the Developer Resources section of Sitecore Search. 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 Sitecore Search APIs. When you authenticate, you tell Sitecore Search that you are a valid user. When you authorize, you tell Sitecore Search 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 Sitecore Search 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 Ingestion API only accepts an API key. It does not accept an access token.
The following sections describe the API key, access token, and refresh token in detail.
API key
The Sitecore Search API key is a unique and secure 52-character secret code. API keys do not expire.
This is a sample API key: 01-90c83624-12f708fa77a1e96a25c4a2afd0f28a4c23ff5252
You cannot generate an API key on your own. Sitecore Search generates it for you. To view your API key, click Developer Resources > API Access.
You can use an API key to optionally generate an access token. Then, add an API key or an access token to a request header.
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:
-
discover- this scope authorizes you to use the Search and Recommendation API. -
event- this scope authorizes you to call the Events API. -
ingestion- this scope authorizes you to call the Ingestion 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 discover 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 Sitecore Search 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 discover scope to generate an access token. You can use the access token that you generate from this API key to call the Search and Recommendation API, but not the Event API.