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}

Replace {version} with preview2 and example.com with your CMS (SaaS) instance's URL.

Request a token

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

Create API client

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

2. Enter a Client ID.

   📘

   Note

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

3. Click Create. Copy the secret from the Client secret field.

   

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

{
  "grant_type": "client_credentials",
  "client_id": "{Client ID}",
  "client_secret": "{Client secret}"
}

Replace {Client ID} and {Client secret} with the values from the create API client section.

Replace {version} with preview2 and example.com with your CMS (SaaS) instance's URL.

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))

grant_type=client_credentials

Replace {version} with preview2 and example.com with your CMS (SaaS) instance's URL.

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

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

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

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

Replace {version} with preview2 and example.com with your CMS (SaaS) instance's URL.

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: