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 Secret to request a token. If you do not have these credentials, create an API key with the following procedure.

Create API key

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

2. Click Create API Key.

   

3. Enter a Name and click Create API Key. The Name can only contain letters, numbers, hyphens, and underscores.

   

4. (Optional) Select Impersonation. 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.

5. The Client ID and Secret is auto-filled. Save these values.

   

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

Request token

After creating an API key, 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 you save from creating the API key.

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 key's.
2. When managing content, the API key's content permissions are evaluated.

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