logo
logo

Authentication

You need an authentication API key to access both the Preview API and the Delivery API.

Provide your authentication key in the header of each request to the Preview and Delivery APIs as the X-GQL-Token parameter.

You can create a key using the token API or from the Sitecore Content Hub UI.

Important

An authentication key is static and does not expire, but can be revoked.

Authentication schemes

The authentication scheme used will depend on the API:

  • X-GQL-Token for GraphQL APIs.
  • JWT bearer for the other APIs.

For more information, see APIs.

Scopes

Scopes limit the access scope of the authentication API key. The following scope types are available:

ScopeUse
AudienceThis authorizes access to the APIs. Use audience-preview to access the Preview API, or audience-delivery to access the Delivery API.
ContentThis provides top-level query access to the entity identified by the ID in the scope parameter, that is everything following the content- prefix. For example, accessing a content collection with ID abc123 requires the scope content-abc123. In addition to individual entity content scopes, the special content-#everything# scope allows access to all content.
Important

When you generate an API key, you should define at least one audience scope and one content scope.

Create an API key from the UI

You can create an authentication API key from the Manage page or from a content collection:

  • API keys created from the Manage page authorize access to the whole Preview API or Delivery API content. That is, the key has the content-#everything# scope.
  • API keys created from a content collection authorize access to this content collection only. That is, the key as a content- scope limited to that content collection.

Create a key from the Manage page

Warning

You must be a superuser to create API keys from the Manage page. Make sure to save created keys because you cannot retrieve them afterwards.

Important

Before creating an API key for the first time, you need to:

  1. Enable content publishing.
  2. Publish your schema (see Publish members or Publish an entity definition).
  3. Wait for background processes to finish.

To create an authentication API key from the Manage page:

  1. On the menu bar, click Manage .
  2. On the Manage page, click API keys.
  3. On the API keys page, to add a key, click + API key.
  4. Define the key name.
  5. Select the purpose of the key (Delivery or Preview).
  6. Click Create.
  7. Copy and save the generated key for future use.
Note

The purpose of the key (step 4.) corresponds to the audience scope.

Create a key from a content collection

Warning

You must have the correct roles to create, use, or manage API keys for content collections. Make sure to save created keys because you cannot retrieve them afterward.

To create an authentication API key from a content collection:

  1. On the menu bar, click Content and select Content Collections.
  2. On the Content collections page, click the desired content collection.
  3. On the detail page of the content collection, click More actions .
  4. Click API keys.
  5. On the API keys screen, to add a key, click + API key.
  6. Define the key name.
  7. Select the purpose of the key (Delivery or Preview).
  8. Click Create.
  9. Copy and save the generated key for future use.
Note

The purpose of the key (step 4.) corresponds to the audience scope.

Can we improve this article ? Provide feedback