Authenticate

14 min

Register OAuth 2.0 apps in Optimizely CMP

To register an app, go to Admin menu > Apps and Webhooks. Under the Apps tab, click Register 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.

Get an authorization code.

Open the web app in a browser. You must be registered with the organization with which the app is associated.

Perform some action in the web app (such as clicking a button) to begin the authorization process. 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.

Log in, if needed. By logging in, you let the app access your data from Optimizely CMP. 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-21098765432

code is the authorization code.

Exchange the authorization code with tokens – 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) Validate the token – 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

Make an Open API request with the token– 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

Refresh the tokens – 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"
  }

🚧 Important A refresh token is valid for a single use only. If you use refresh_token to refresh access_token once, you cannot use it to refresh the access_token again. You must use the refresh_token returned with the response for the refreshed access_token next time.

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.

🚧 Important Avoid making requests too frequently to prevent rate limiting on token generation requests. Because tokens have a specific expiry period, reuse previously generated tokens until they are close to expiring. Request a new token through the client credential flow shortly before the current token expires or when you receive a 401 error indicating the token has expired.

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

CMP DAM Asset Picker in CMSCMP DAM Asset Picker in CMS