Managing SitecoreAI client credentials

Create a JSON web token for the Authoring and Management API or the Deploy API

To run any operation on the Sitecore Authoring and Management GraphQL API or the Deploy REST API, obtain an authentication token in JSON Web Token (JWT) format and include it in every call to the API. These APIs use the OAuth authorization framework.

Note

You can also create a JSON web token for Experience Edge APIs.

Create a JSON web token

Note

Before you begin

For the Authoring and Management API of a specific environment, create an environment automation client.
For the Authoring and Management APIs of all environments in an organization, or for the Deploy REST API, create an organization automation client.

Creating an automation client generates a client ID and client secret. You'll use the client ID and client secret when creating a JWT.

Follow the principle of least privilege when choosing which type of automation client to create. Use an environment automation client when your automation targets a specific environment so that a leaked client secret cannot be used to access other environments or organization-level APIs. Use an organization automation client when you need access across all environments or require organization-level operations such as creating new environments.

To request a JSON web token (JWT), make the following HTTP request using either a JSON or a URL-encoded format:

POST https://auth.sitecorecloud.io/oauth/token

You must provide the following required attributes in the request body:

Attribute	Type	Description	Value
audience	string	The group of APIs the JWT is intended for.	https://api.sitecorecloud.io
grant_type	string	The method used to obtain the JWT.	client_credentials
client_id	string	The client ID.If you don't know this value, first create an automation client.	Your client ID.Example: or27P5db...
client_secret	string	The client secret.If you don't know this value, first create an automation client.	Your client secret.Example: ctrWEP7Rd3...

JSON

curl

curl -X POST 'https://auth.sitecorecloud.io/oauth/token' \\
-H 'Content-Type: application/json' \\
--data-raw '{
    "audience": "https://api.sitecorecloud.io",
    "grant_type": "client_credentials",
    "client_id": "<YOUR_CLIENT_ID>",
    "client_secret": "<YOUR_CLIENT_SECRET>"
}'

URL-encoded

curl

curl -X POST 'https://auth.sitecorecloud.io/oauth/token' \\
-H 'content-type: application/x-www-form-urlencoded' \\
--data-urlencode 'audience=https://api.sitecorecloud.io' \\
--data-urlencode 'grant_type=client_credentials' \\
--data-urlencode 'client_id=<YOUR_CLIENT_ID>' \\
--data-urlencode 'client_secret=<YOUR_CLIENT_SECRET>'

Here's an example response:

json

{
    "access_token": "eyJhbG...",
    "scope": "...",
    "expires_in": 86400,
    "token_type": "Bearer"
}

In the response:

access_token is the JSON web token. You can use the JWT to authorize requests to the Authoring and Management GraphQL API or the Deploy REST API.
scope defines the resources the JWT provides access to. The resources depend on the type of credentials you created.
expires_in defines the validity of the JWT in seconds. Note that JWTs typically expire in 24 hours. After that time, the token is no longer valid and you must request a new token.
token_type defines the type of token created, such as Bearer.

Security considerations

JWTs issued by Sitecore are signed using RS256. Before using a JWT, use your JWT library to validate it against Sitecore's JSON Web Key Set (JWKS) URI:

https://auth.sitecorecloud.io/.well-known/jwks.json

The JWKS URI provides the public keys used to verify the signature. Configure your JWT library to check the expected issuer (https://auth.sitecorecloud.io/) and audience (https://api.sitecorecloud.io), and ensure expiry checking is not disabled. Consult your library's documentation to confirm which of these are validated automatically. Never use a JWT you did not obtain directly from your own credentials request.

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