Authenticate

Optimizely CMP Open API uses OAuth 2.0 as its authorization mechanism. Register an OAuth 2.0 app for an Optimizely Content Marketing Platform (CMP) organization to use the API.

Optimizely Content Marketing Platform (CMP) Open API uses OAuth 2.0 as its authorization mechanism. Register an OAuth 2.0 app for a CMP organization to use the API by going to Admin menu > Apps and Webhooks. Under the Apps tab, click Register App.

Register OAuth 2.0 apps in Optimizely CMP

To register an app, provide the following information:

Mode – Select between Production or Development mode for the preset configuration of the app.
Name – Enter a name for the app you want to register.
Description – Description of the app that you want to register.
Expose Email Addresses? – Select whether you want to display the user's email addresses.
Homepage URL – Enter the full URL to your application page.
Authorization Callback URL – A valid URL of the server hosting the web app, where the Optimizely CMP authorization server sends the authorization code.

When your registration is successful, Optimizely CMP sends you a client_id and a client_secret with which you can request an access_token and refresh_token from the Optimizely CMP authorization server.

The supported OAuth 2.0 flow is authorization code and Client Credentials. In these flows the OAuth 2.0 app must be a web app hosted on a server. The server hosting the web app must know and protect the client id and client secret.

Authorization server

Host – https://accounts.cmp.optimizely.com
Authorization endpoint – https://accounts.cmp.optimizely.com/o/oauth2/v1/auth
Scopes – openid, profile and offline_access (A single space delimits these scopes and must be passed to the authorization endpoint.)
Token endpoint – https://accounts.cmp.optimizely.com/o/oauth2/v1/token
Userinfo endpoint (can be used to validate access token) – https://accounts.cmp.optimizely.com/o/oauth2/v1/userinfo

Authorization code flow

Optimizely CMP supports the authorization code flow for OAuth 2.0.

Open the web app in a browser. You must be registered with the organization with which the app is associated.
1. Perform some action in the web app (such as clicking a button) to begin the authorization process.
2. You are redirected to the authorization server.
```
HTTP GET
https://accounts.cmp.optimizely.com/o/oauth2/v1/auth?client_id=12345678-1234-1234-1234-123456789012&redirect_uri=https://my-web-app.com/o/oauth/callback&response_type=code&scope=openid%20profile%20offline_access
```
  client_id is the client id of the app that you have registered, and redirect_uri is the redirect url of the app provided when the app was registered.
3. Authorization server logs you in, if not already logged in. By logging in, you let the app access your data from Optimizely CMP.
4. You are redirected to the redirect URL of the app with the authorization code.
```
HTTP GET
https://my-web-app.com/o/oauth/callback?code=87654321-4321-4321-4321-210987654321
```
  code is the authorization code.

The web app makes an HTTP POST request to the authorization server to obtain an access_token and a refresh_token.

HTTP POST  
    https://accounts.cmp.optimizely.com/o/oauth2/v1/token
    Request payload:
    {
        "client_id"     : "12345678-1234-1234-1234-123456789012",
        "client_secret" : "my-encrypted-secret-1234",
        "code"          : "87654321-4321-4321-4321-210987654321",
        "grant_type"    : "authorization_code",
        "redirect_uri"  : "https://my-web-app.com/o/oauth/callback"
    }

Response payload:
    {
        "access_token"  : "b3717c0a-6857-4858-8274-9fe7b51180c9",
        "refresh_token" : "ff7d31df-ad4d-4a62-9291-877df0757478",
        "id_token"      : "some-jwt-token",
        "expires_in"    : 3599,
        "token_type"    : "Bearer"
    }

(Optional) The server can validate the received access token by making an HTTP GET request to the authorization server by passing the access_token in the Authorization HTTP header with the Bearer prefix. For example
```
HTTP GET  
https://accounts.cmp.optimizely.com/o/oauth2/v1/userinfo

Headers:
  Authorization: Bearer b3717c0a-6857-4858-8274-9fe7b51180c9
```
The web server can use the Open API by passing the access_token in the Authorization HTTP header with the Bearer prefix. For example
```
HTTP GET  
https://api.cmp.optimizely.com/v3/assets

Headers:
  Authorization: Bearer b3717c0a-6857-4858-8274-9fe7b51180c9
```

If the access_token expires, the web server can get an access_token, using the refresh_token, by making an HTTP POST request to
the authorization server

HTTP POST  
https://accounts.cmp.optimizely.com/o/oauth2/v1/token

Request payload:
  {
    "client_id"     : "12345678-1234-1234-1234-123456789012",
    "client_secret" : "my-encrypted-secret-1234",
    "refresh_token" : "ff7d31df-ad4d-4a62-9291-877df0757478",
    "grant_type"    : "refresh_token"
  }

Response payload:
  {
    "access_token"  : "bd680785-b090-40ca-9a32-22df51e96e7a",
    "refresh_token" : "e053d83e-14e1-4ba4-b18e-ea654b39a02e",
    "id_token"      : "some-jwt-token",
    "expires_in"    : 3599,
    "token_type"    : "Bearer"
  }

Client credentials flow

Optimizely CMP supports the client credentials flow. The client credentials flow is an OAuth 2.0 flow designed for machine-to-machine authentication. It enables your application to securely access resources on behalf of itself, rather than on behalf of a user. This flow is particularly useful for applications that need to perform operations without user interaction.

The web app makes an HTTP POST request to the authorization server to obtain an access_token.

HTTP POST  
    https://accounts.cmp.optimizely.com/o/oauth2/v1/token
    Request payload:
    {
        "client_id"     : "12345678-1234-1234-1234-123456789012",
        "client_secret" : "my-encrypted-secret-1234",
        "grant_type"    : "client_credentials"
    }

Response payload:
    {
        "access_token"  : "b3717c0a-6857-4858-8274-9fe7b51180c9",
        "expires_in"    : 3599,
        "token_type"    : "Bearer"
    }

The web server can use the Open API by passing the access_token in the Authorization HTTP header with the Bearer prefix. For example:
```
HTTP GET  
https://api.cmp.optimizely.com/v3/assets

Headers:
  Authorization: Bearer b3717c0a-6857-4858-8274-9fe7b51180c9
```

Enable or disable the client credentials flow

You can enable or disable the client credentials flow for your app from the app settings page.

Go to Apps & Webhooks in the browser
Click your app.
Find the Authorization Permissions section
Toggle the Allow Client Credentials option to enable or disable the client credentials flow

Client credentials flow security concern

The client credentials flow is less secure than the authorization code flow because it relies on a client ID and secret for authentication without user involvement. This means if the secret is compromised, attackers can access resources without user control or revocation. Additionally, the secret must be securely stored on the server, and frequent token requests increase the risk of exposure. Due to these risks, this flow should only be used in secure, trusted environments like server-to-server communication, where the secret can be tightly controlled and protected from unauthorized access.

For better security, use the authorization code flow and disable the client credentials flow for your app from your apps settings.

Organization association

An app is associated with one Optimizely CMP organization. An app cannot be associated with multiple Optimizely CMP organizations.

Resource owner

The resource owner authorizing the app, such as an Optimizely CMP user accessing data through the Open API, must be registered with the associated organization.

App modes

You can create apps in development or in production mode. If you plan to develop an app and not publish it to real users, you can leverage the development mode for a longer time to live (TTL).

Development mode

TTL for access token – 30 days
TTL for refresh token – 365 days

Production mode

TTL for access token – 1 hour
TTL for refresh token – 365 days