Create a Sitecore services client API key

Version: 22.x

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.

Important

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:

  1. From the Tools tab on the Dashboard, open the Content Editor application.

  2. In the content tree, navigate to /sitecore/system/Settings/Services/API Keys.

  3. 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.

  4. 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:

      RequestResponse
        Sitecore.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.

      Note

      Authenticated users (with valid Sitecore authentication cookies) receive their own security context regardless of this setting. This setting applies only to anonymous requests.

      Warning

      Never use the sitecore\admin or any other privileged user as the impersonation user as this allows for severe security breaches. Use only extranet\anonymous or an app-specific dedicated user for impersonation.

  5. Save and publish the API key item.

  6. 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>.

    Note

    If you do not provide the api_item_id, the server returns an error HTTP 400 - Bad Request.

    Add the URL parameter sc_site for multisite solutions and sc_mode=normal to disable editing mode layout data

    If the request resolves correctly, the response returns JSON data similar to:

    RequestResponse
    {
      "context": {
        ...
      },
      "route": {
        "name": "Home",
        ...
      }
    }
  7. Copy the Item ID. You must provide this ID when connecting the JSS app to Sitecore.

Do you have some feedback for us?

If you have suggestions for improving this article,