Authentication and authorization

Authentication

To use 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://api.cms.optimizely.com/<version>/<endpoint>
Authorization: Bearer <your_access_token>

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 using the following instructions.

Create API key

Go to Settings > API Keys in your CMS (SaaS) instance.
Click Create API Key.
Enter a Name and click Create API Key. The Name can only contain letters, numbers, hyphens, and underscores.
(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.
The Client ID and Secret are 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 expires.

JSON

POST https://api.cms.optimizely.com/oauth/token
Content-Type: application/json

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

Replace CLIENT_ID and CLIENT_SECRET with the values you saved from creating the API key.

X-www-form-urlencoded

POST https://api.cms.optimizely.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Base64(GetBytes(client_id:client_secret))

grant_type=client_credentials

Response

When you provide correct credentials, 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 expires.

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://api.cms.optimizely.com/oauth/token
Content-Type: application/json

{
  "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:

When a user is impersonated, the user's permissions are evaluated in addition to the API key's.
When managing content, the API key's content permissions are evaluated.

Find API key content permissions on the Set Access Rights page. Go to Settings > Set Access Rights, as shown in the following image: