API keys for the OData Item Service

Current version: 10.3

You must pass a valid API key in each request to the OData Item Service. If you do not, the request fails.

The API key is the ID of an item that you create in the master database. Long and short IDs are both valid forms of an API key. For example:

12239A2A-D323-4236-8CA7-0D01C1A17AC6

12239A2AD32342368CA70D01C1A17AC6

You create API key items in the master\sitecore\system\Settings\Services\API Keys folder, using the sitecore\templates\System\Services\API Key template. You must publish the items you create.

The API Key template has three fields:

Field

Description

AllowedControllers

A semicolon-separated list of controllers allowed to use the API key. You can use the "*" wildcard character to allow all controllers.

For example: CustomService.Controllers.ApiKeyAttributeController

CORS Origins

A semicolon-separated list of allowed origins.

Example: http://sdn1.samplesite.com; http://cdn2.samplesite.com;http://anothersite.com

Note

If Sitecore is running in Azure Web Apps, CORS origins can be managed by either Sitecore or Azure exclusively. It is not possible to use both for managing CORS, as Azure configuration always overrides the configuration coming from an application (Sitecore). To manage CORS from Sitecore: remove all CORS configurations from the Azure portal. Then use the CORS Origins field to add CORS domains. To manage CORS from an Azure portal: add all the necessary domains to the CORS configuration in the portal.

Impersonation User

Anonymous users are impersonated as this user.

Example: sitecore\User.

If you do not specify Impersonation User in API Key, the value specified in the Sitecore.Services.AnonymousUser configuration setting is used.

You can add more fields to the items. This data is available in the CustomData property as a key-value Dictionary object.

Note

The OData Item API Key template is an extended version of the API Key template for the ODATA Item Service. The template for OData Item API key is inherited from API Key template and it introduces two fields (Database, and Search Filter Field) used by the OData Item Service. The value of these fields is available in the CustomData property as a key-value Dictionary object. This template is in the master database: sitecore\templates\System\Services\OData Item API Key.

This topic describes:

Using an API key

You pass the (long or short) ID of an API key item in a request, either as a query parameter or in the header.

Passing an API key in query parameters

Using the long ID of an API key item:

/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?sc_apikey=26192A5F-9530-4D8D-AB0A-0A608F99B060

Using the short ID of an API Key item:

/sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')?sc_apikey=26192A5F95304D8DAB0A0A608F99B060

Passing an API key in the header

Using the long ID of an API key item:

  • URL: /sitecore/api/ssc/aggregate/content/Items('{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}')

  • Header_key: sc_apikey

  • Header_value: 26192A5F-9530-4D8D-AB0A-0A608F99B060

The [RequiredApiKey] class attribute

You can use the [RequiredApiKey] attribute on a controller to ensure that the API key is available either in the request URL or in headers.

After the Sitecore.Services.Client has validated the API key, it also checks if this particular controller is mentioned in the AllowedControllers properties of the API key item. If not, it fails and throws the bad request error (HTTP status code 400).

Do you have some feedback for us?

If you have suggestions for improving this article,