Create a Sitecore services client API key
The services used by JSS, such as the Layout Service, GraphQL, and Dictionary Service, require a Sitecore services client API key. You must create this key and note its Item ID for using it when connecting JSS apps to Sitecore.
This only applies to full-stack development within a local Docker Sitecore environment. For connecting to an XM Cloud environment, you can use the Context ID.
To create a Sitecore services client API key:
-
From the Tools tab on the Dashboard, open the Content Editor application.
-
In the content tree, navigate to /sitecore/system/Settings/Services/API Keys.
-
On the Home ribbon, insert a new API Key item. The name of the item is for your reference only. Pick a meaningful name, such as the name of your JSS app.
-
Set up the following fields on the API key:
-
CORS Origins: If you are using connected mode, the APIs must support CORS so that your development server host, by default
http://localhost:3000
, is allowed to make HTTP requests to Headless Services. For local development, use*
to allow all origins. In production, only allow specific origins. Specify multiple origins by separating them with a semicolon;
. -
AllowedControllers: It is possible to use the asterisk
*
to allow all controllers, but explicitly allowlisting specific controllers is a best practice. If you use additional controllers, they must be added to this list. For example:RequestResponseSitecore.LayoutService.Mvc.Controllers.LayoutServiceController; Sitecore.JavaScriptServices.Globalization.Controllers.DictionaryServiceController; Sitecore.Services.GraphQL.Hosting.Mvc.GraphQLController; GraphQL:/api/yourappname
-
Impersonation User: always specify an explicit user. The impersonation user is a Sitecore user whose security context is used to determine the security rights of the JSS app to Sitecore content. Most apps must use
extranet\anonymous
, giving them the same security context as an anonymous web user.NoteAuthenticated users (with valid Sitecore authentication cookies) receive their own security context regardless of this setting. This setting applies only to anonymous requests.
WarningNever use the
sitecore\admin
or any other privileged user as the impersonation user as this allows for severe security breaches. Use onlyextranet\anonymous
or an app-specific dedicated user for impersonation.
-
-
Save and publish the API key item.
-
Verify the Sitecore Headless Services module is working by visiting the REST Layout Service endpoint at
<sitecore_server>/sitecore/api/layout/render?item=/&sc_apikey=<api_item_id>
.NoteIf you do not provide the
api_item_id
, the server returns an errorHTTP 400 - Bad Request
.Add the URL parameter
sc_site
for multisite solutions andsc_mode=normal
to disable editing mode layout dataIf the request resolves correctly, the response returns JSON data similar to:
RequestResponse{ "context": { ... }, "route": { "name": "Home", ... } }
-
Copy the Item ID. You must provide this ID when connecting the JSS app to Sitecore.