API keys for the OData Item Service

Last updated Tuesday, December 5, 2017 in Sitecore Experience Platform for Developer
Keywords: Development

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 core 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 core\sitecore\system\Settings\Services\API Keys folder, using the sitecore\templates\System\Services\API Key template.

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

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 core 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).

Send feedback about the documentation to docsite@sitecore.net.