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.

Enable the GraphQL IDE

Using the IDE requires that you are at least in the sitecore\Sitecore Client Users role.

Before using the GraphQL IDE, you must enable it in your settings.

To enable the GraphQL IDE:

  1. In XM Cloud Deploy, create an environment variable named Sitecore_GraphQL_ExposePlayground with a true value. If already present, update the environment variable value to true.

    Important

    We recommend that you only enable the GraphQL IDE in nonproduction environments.

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

  1. Log in to your XM Cloud environment by running the dotnet sitecore cloud login command and following the prompts.

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

To obtain an additional access token:

  1. Create an automation client for your environment and use the client credentials flow by running the following command:

    RequestResponse
    dotnet sitecore cloud login --client-credentials --client-id <your-client-id> --client-secret <your-client-secret> --allow-write true --xmcloudhost <your-xmcloud-host> --authority <authority-url> --audience <audience-url>

    By default, the authority URL is https://auth.sitecorecloud.io, and the audience URL is https://api.sitecorecloud.io.

  2. Request a Bearer token with the following command:

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

    RequestResponse
    {
  "access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkZXZ2VHTFpCWGZJcjhKZy1ieDgxRSJ9.eyJodHRwczovL2F1dGguc2l0ZWNvcmVjbG91ZC5pby9jbGFpbXMvdGVuYW50L2NkcF9jbGllbnRfa2V5IjoiMjhiMjNkZjYzZGIwMDdjMmRjYWJjMmI5NzI5YzI4YTgiLCJodHRwczovL2F1dGguc2l0ZWNvcmVjbG91ZC5pby9jbGFpbXMvb3JnX2lkIjoib3JnX0prOVJKYlFQYTBtOVBzdWwiLCJodHRwczovL2F1dGguc2l0ZWNvcmVjbG91ZC5pby9jbGFpbXMvb3JnX25hbWUiOiJ4bWNsb3VkLXRlc3Qtb3JnYW5pemF0aW9uIiwiaHR0cHM6Ly9hdXRoLnNpdGVjb3JlY2xvdWQuaW8vY2xhaW1zL29yZ19kaXNwbGF5X25hbWUiOiJYTUNsb3VkIFRlc3QgT3JnYW5pemF0aW9uIiwiaHR0cHM6Ly9hdXRoLnNpdGVjb3JlY2xvdWQuaW8vY2xhaW1zL2NsaWVudF9uYW1lIjoiYW5jYS1kb2MtZGV2IiwiaHR0cHM6Ly9hdXRoLnNpdGVjb3JlY2xvdWQuaW8vY2xhaW1zL3RlbmFudF9pZCI6IjIxNTMzOWRmLWZlODEtNGY4Yy0zNDIxLTA4ZGFjNjIzMDNiYyIsImh0dHBzOi8vYXV0aC5zaXRlY29yZWNsb3VkLmlvL2NsYWltcy90ZW5hbnRfbmFtZSI6InhtY2xvdWR0ZXN0Y2M0Yy1kb2NzYW5jYS1kZXYtcyIsImlzcyI6Imh0dHBzOi8vYXV0aC1zdGFnaW5nLTEuc2l0ZWNvcmUtc3RhZ2luZy5jbG91ZC8iLCJzdWIiOiJxQjFRc0ZxSGJqaWpVQkt3dVJKSWx4VlJFVlowcVZ6TUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9hcGktc3RhZ2luZy5zaXRlY29yZS1zdGFnaW5nLmNsb3VkIiwiaWF0IjoxNjY4Nzg0NzU0LCJleHAiOjE2Njg3ODU2NTQsImF6cCI6InFCMVFzRnFIYmppalVCS3d1UkpJbHhWUkVWWjBxVnpNIiwic2NvcGUiOiJ4bWNsb3VkLmNtOmFkbWluIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.mbV5eXBfm8AskRT8_pmfvigMuNxAvwSF4A3R7Ku1Hr2JdRV0kJ_Uv3hVBG8Pcv1oeeFTQBqDGZVX42QUXQJX1IrDBxRvmTAoBoY9V0ORXuY9i6nbC-zqwVm-laUjxNHqoc09eHsQiRoyfCTk3RiVsAkY6mjGIwMgfepmx921MO49X9ueqd4_D05-SM-T_fJPfIKT2aMWXt9Uuvj5UYJ358a55mGP29wJnfs4S4NtTZqHEPc05IJNcI0kYJC5KgvIdRSSWTq-lq7bloRvPRWeUWqYvYSzAf_5Vu7uIZoYzupe-4Gah9NnAWemWQURW-mhDVkXFqFPT5zLRIFIVUgdMg",
  "scope":"xmcloud.cm:admin",
  "expires_in":900,
  "token_type":"Bearer"
}

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

  1. Open the IDE in the browser at https://<your-server>/sitecore/api/authoring/graphql/playground/.

  2. In the IDE's lower-left pane, on the HTTP Headers tab, add the authorization header with the following format:

    RequestResponse
    {
    "Authorization": "Bearer <access-token>"
}

    Replace the <access-token> placeholder with the value you copied.

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

  4. Verify your setup by running a query. For example:

    RequestResponse
    query {
  sites {
    name
  }
}

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

    RequestResponse
    {
  "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:

    RequestResponse
    {
    headers: [
        { "Authorization": "Bearer <access-token>" }
    ]
}

Do you have some feedback for us?

If you have suggestions for improving this article,