Walkthrough: Enabling and authorizing requests to the Authoring and Management API

You can explore the Authoring and Management API with an interactive browser-based GraphQL IDE or through HTTP requests.

Querying the GraphQL Authoring and Management API programmatically or using the GraphQL IDE requires authorization.

This walkthrough describes how to:

Enable the GraphQL IDE.
Obtain an access token.
Obtain an additional access token (optional).
Authorize the GraphQL IDE.
Authorize HTTP requests.

Note

This walkthrough assumes you are running commands in PowerShell 7 or later. Earlier versions of PowerShell might not interpret the curl command correctly and can result in errors like those described here. If you encounter issues, ensure you are using PowerShell 7 or later, or run commands directly in a terminal that supports curl (such as Git Bash or WSL).

Enable the GraphQL IDE

To use the GraphQL IDE, you must enable it in your settings. You must have, at a minimum, the sitecore\Sitecore Client Users role.

Note

The GraphQL IDE is intended to support development and exploratory use and is not required for normal operation of the GraphQL APIs.

To enable the GraphQL IDE:

In Deploy, create an environment variable named Sitecore_GraphQL_ExposePlayground with a true value. If already present, update the environment variable value to true.
For the environment variable to take effect, redeploy your environment.

Obtain an access token

You must obtain an access token to authorize the GraphQL IDE or HTTP requests to perform operations against the Authoring and Management API endpoint.

To obtain an access token:

Log in to your environment by running the dotnet sitecore cloud login command in the Sitecore CLI and following the prompts.
When logged in, the process stores an access token that you can use to set the necessary Authorization header for the GraphQL IDE and HTTP requests. From the ./sitecore/user.json file, copy the value of the accessToken property and store it for later use,

If you do not require additional tokens or automation clients, continue to authorize the GraphQL IDE.

Obtain an additional access token (optional)

You can generate additional tokens if you require or prefer to use multiple tokens/automation clients, for example, one for HTTP requests and another for the GraphQL IDE.

XM Cloud is now SitecoreAI

Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

To obtain an additional access token:

Create an automation client for your environment. By default, the authority URL is https://auth.sitecorecloud.io, and the audience URL is https://api.sitecorecloud.io.

Request a Bearer token with the following command:

curl --location --request POST '<authority-url>/oauth/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=<your-client-id>' --data-urlencode 'client_secret=<your-client-secret>' --data-urlencode 'audience=<audience-url>' --data-urlencode 'grant_type=client_credentials'

Replace the placeholders as follows:

<authority-url> - with the value of endpoints.xmCloud.authority value from the .sitecore/user.json file.
<your-client-id> - with the value of endpoints.xmCloud.clientId value from the .sitecore/user.json file.
<your-client-secret> - with the value of endpoints.xmCloud.clientSecret value from the .sitecore/user.json file.
<audience-url> - with the value of endpoints.xmCloud.audience value from the .sitecore/user.json file.

If successful, the response is printed in the console.

{
  "access_token":"eyJhbGciOiJSUzI1NiIs...",
  "scope":"xmcloud.cm:admin",
  "expires_in":900,
  "token_type":"Bearer"
}

From the response, copy the access_token value without quotation marks and store the token for later use.

Important

Pay attention to the expires_in property of the response. It indicates the JWT token expiration period. After that time, the token is invalid, and you must request a new token.

Authorize the GraphQL IDE

Before performing queries and mutations in the GraphQL IDE, you must authorize the IDE to perform operations.

To set the correct headers for the GraphQL IDE:

Open the IDE in the browser at https://<your-server>/sitecore/api/authoring/graphql/ide/.
In the IDE's lower-left pane, on the HTTP Headers tab, add the authorization header with the following format:
{ "Authorization": "Bearer <access-token>" }
Replace the <access-token> placeholder with the value you copied.
In the IDE's endpoint field (to the right of the History tab), verify that the endpoint is https://<your-instance>/sitecore/api/authoring/graphql/v1/.

Verify your setup by running a query. For example:

query {
  sites {
    name
  }
}

If the configuration is correct, the response contains a list of your websites. For example:

{
  "data": {
    "sites": [
      {
        "name": "Winter Wonderland"
      },
      {
        "name": "website"
      }
    ]
  }
}

Authorize HTTP requests

HTTP requests against the Authoring and Management API endpoint require authorization.

To authorize your HTTP requests:

Include the HTTP Authorization header with the Bearer authentication scheme. Replace the <access-token> placeholder with the value of the access token. For example:
{ headers: [ { "Authorization": "Bearer <access-token>" } ] }

If you have suggestions for improving this article, let us know!