Authorization and API access

Authorize requests to the GraphQL APIs

There are three ways to access the Preview GraphQL API and the Delivery GraphQL API:

• GraphQL IDE - the GraphQL IDE (GraphQL Playground) is the recommended tool for exploring and testing queries during development. Using it helps you understand the response structure and efficiently debug your front-end code. You authorize requests in the IDE using an API token generated directly in SitecoreAI Deploy. For step-by-step instructions, see Set up the GraphQL IDEs.

• Front-end app - in your front-end app, we recommend you use the same endpoint for both the Preview GraphQL API and the Delivery GraphQL API, and use Context IDs rather than an API token to authorize requests. You use the Preview Context ID for the Preview GraphQL API, and the Live Context ID for the Delivery GraphQL API.

  There are two main reasons we recommend using this approach for modern development: first, it's simpler to set up and maintain than the direct API access approach. Second, following this approach, you switch between the Preview GraphQL API and the Delivery GraphQL API by switching Context IDs. You don't need to modify the endpoint or any other part of the request.

  Important

  Avoid exposing your Context IDs to the browser.

• Direct API access - as an alternative to the approach recommended for front-end development, you could make direct API requests using the native API endpoints and authorization methods. In this scenario, you authorize requests using the same API tokens used in the GraphQL IDEs.

curl -X POST 'https://edge-platform.sitecorecloud.io/v1/content/api/graphql/v1' \
--header 'x-sitecore-contextid: <PREVIEW_CONTEXT_ID>' \
--header 'Content-Type: application/json' \
--data-raw '{<GRAPHQL_QUERY>}'

curl -X POST 'https://<YOUR_ENVIRONMENT_HOST_NAME>/sitecore/api/graph/edge' \
--header 'sc_apikey: <PREVIEW_API_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'Cookie: shell#lang=en' \
--data-raw '{<GRAPHQL_QUERY>}'

curl -X POST 'https://edge-platform.sitecorecloud.io/v1/content/api/graphql/v1' \
--header 'x-sitecore-contextid: <LIVE_CONTEXT_ID>' \
--header 'Content-Type: application/json' \
--data-raw '{<GRAPHQL_QUERY>}'

curl -X POST 'https://edge.sitecorecloud.io/api/graphql/v1' \
--header 'sc_apikey: <DELIVERY_API_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'Cookie: shell#lang=en' \
--data-raw '{<GRAPHQL_QUERY>}'

Authorize requests to the Admin REST API and the Token REST API

Here's an example cURL call for accessing the Admin REST API:

curl -X GET 'https://edge.sitecorecloud.io/api/admin/v1/<ENDPOINT>' \
--header 'Authorization: Bearer <JSON_WEB_TOKEN>'

Here's an example cURL call for accessing the Token REST API:

curl -X GET 'https://edge.sitecorecloud.io/api/apikey/v1' \
--header 'Authorization: Bearer <JSON_WEB_TOKEN>'

Note the following:

• The base URL for the Admin REST API:

  https://edge.sitecorecloud.io/api/admin/v1

• The base URL for the Token REST API:

  https://edge.sitecorecloud.io/api/apikey/v1

• The Admin REST API and the Token REST API both use bearer authorization with a JSON web token (JWT). To authorize API requests:

  1. Create an Edge administration client for your environment in SitecoreAI Deploy. This generates a client ID and client secret.

  2. Create a JSON web token using the client ID and client secret. This generates a JWT. JSON web tokens expire after 24 hours. After expiry, request a new one.

  3. Include the JWT in the header of every API request you make:

     Authorization: Bearer <JSON_WEB_TOKEN>

Programmatically create Delivery GraphQL API tokens

The recommended way to authorize requests to the Delivery GraphQL API is by using a Context ID in your front-end app or an API token in the GraphQL IDE. The simplest way to get an API token is to generate it in SitecoreAI Deploy, on the Details tab of your environment.

Alternatively, you can create Delivery GraphQL API tokens programmatically, using either the Deploy REST API or the Token REST API. These methods are not available for the Preview GraphQL API.

The API tokens you programmatically generate can be used the same way as the ones you create in SitecoreAI Deploy.