Create a Sitecore services client API key

Current version: 22.x

The services used by JSS, such as the Layout Service, GraphQL, Tracking Service, and Dictionary Service, utilize the API Key mechanism provided by Sitecore Services Client (SSC). You must create a Sitecore services client API key, and note its Item ID to use it when connecting JSS apps to Sitecore.

To create a Sitecore services client API key:

  1. Log into Sitecore and open the Desktop application and select the core or master database.

    Note

    In Sitecore 9.0, using the database icon in the lower right, switch to the core database. In Sitecore 9.1 and later, the Sitecore services client API key is stored in the master database, which is the default, so this step is unnecessary.

    Switch the database to master in Sitecore 9.0.
  2. From the start menu or from the Sitecore Launchpad, open the Content Editor application.

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

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

  5. 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 whitelisting 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.

  6. Save the API key item. In Sitecore 9.1+, publish the item.

  7. Verify the Sitecore Headless Services module is working by visit the REST Layout Service endpoint at <cm_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",
        ...
      }
    }
    
  8. 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,