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

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.

To enable the GraphQL IDE:

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

Obtain an access token

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

To obtain an access token:

1. Log in to your environment by running the dotnet sitecore cloud login command in the Sitecore CLI 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 HTTP requests. From the ./sitecore/user.json file, copy the value of the accessToken property and store it for later use.

Obtain an additional access token (optional)

You can generate additional tokens if you require or prefer to use multiple tokens/automation clients for HTTP requests.

To obtain an additional access token:

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

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

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

Access the GraphQL IDE

To access the GraphQL IDE, you must be authenticated to your tenant and have a valid user account on your Sitecore AI instance. Your user account is created when you first log in to the Sitecore AI instance and access an application such as the Content Editor.

To open and use the GraphQL IDE:

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

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

3. 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>" }
      ]
  }