Authentication and authorization

Authentication

To use the CMS (SaaS) REST API, you must authenticate calls with a bearer JSON Web Token (JWT) by requesting a JWT from the token endpoint with the OAuth 2.0 protocol and then specify the token as a bearer in the Authorization header:

GET https://EXAMPLE.COM/_cms/VERSION/contenttypes
Authorization: Bearer {JWT}

Request a token

You need a Client ID and Client secret to request a token. If you do not have these credentials, follow the Create API client section.

Create API client

1. In your CMS (SaaS) instance, go to Settings > API Clients.

2. Enter a Client ID. Leave the Client secret blank.

   📘

   Note

   The Client ID can only contain letters, numbers, hyphens, and underscores.

3. (Optional) Select Allow the client to impersonate others. This lets the client act as the user authorized to access resources. Use this when you need the client application to perform actions on behalf of the user without the user being directly involved or present.

4. Click Create. The Client secret is auto-filled. Copy the secret from the Client secret field.

   

You can restrict what operations the API Client can execute. See the Authorization section.

Request token

After creating an API client, you can request a token for the API client using application/json or application/x-www-form-urlencoded using basic authentication. The token is valid for 300 seconds (five minutes). Request a new token when this token has expired.

JSON

POST https://EXAMPLE.COM/_cms/VERSION/oauth/token
Content-Type: application/json

Replace VERSION with preview2 and EXAMPLE.COM with your CMS (SaaS) instance's URL.

{
  "grant_type": "client_credentials",
  "client_id": "CLIEND_ID",
  "client_secret": "CLIENT_SECRET"
}

Replace CLIENT_ID and CLIENT_SECRET with the values from the create API client section.

X-www-form-urlencoded

POST https://EXAMPLE.COM/_cms/VERSION/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Base64(GetBytes(client_id:client_secret))

Replace VERSION with preview2 and EXAMPLE.COM with your CMS (SaaS) instance's URL.

grant_type=client_credentials

Response

When correct credentials are provided, a JWT is returned in the access_token property:

{
  "access_token": "[REDACTED]",
  "expires_in": 300,
  "token_type": "Bearer"
}

Copy the access_token to use with your API calls. The token is valid for 300 seconds (five minutes). Request a new token when this token has expired.

Impersonation

To make API calls on behalf of a user instead of an API client, configure the client to let you use impersonation, then when requesting a token, specify the username in the act_as property:

POST https://example.com/_cms/{version}/oauth/token
Content-Type: application/json

Replace VERSION with preview2 and EXAMPLE.COM with your CMS (SaaS) instance's URL.

{
  "grant_type": "client_credentials",
  "client_id": "[REDACTED]",
  "client_secret": "[REDACTED]",
  "act_as": "[email protected]"
}

Authorization

Currently, no authorization takes place except in the following cases:

1. When a user is impersonated, the user's permissions are evaluated instead of the API client's.
2. When managing content, the API client's content permissions are evaluated.

API client content permissions are on the Set Access Rights page. Go to Settings > Set Access Rights: