Authorization and API access

Create a JSON web token for Experience Edge APIs

Creating a JSON web token (JWT) is a required part of authorizing requests to the Admin REST API and the Token REST API, and it also lets you programmatically create Delivery GraphQL API tokens. Note that the recommended approach for creating API tokens for the Delivery GraphQL API is to generate them directly in SitecoreAI Deploy.

Note

You can also create a JWT for the Authoring and Management API or the Deploy REST API.

Create a JSON web token

Before you begin

Create an Edge administration client for your environment in SitecoreAI Deploy. This generates a client ID and client secret. You'll use the client ID and client secret when creating a JWT.

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 of your Edge administration client. If you don't know this value, first create an Edge administration client for your environment.	Your client ID. Example: `or27P5db...`
`client_secret`	string	The client secret of your Edge administration client. If you don't know this value, first create an Edge administration client for your environment.	Your client secret. Example: `ctrWEP7Rd3...`

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>"
}'

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 Admin REST API and the Token REST API, or to programmatically create Delivery GraphQL API tokens.
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!