Get started with CMP API

The Optimizely Content Marketing Platform (CMP) Open API uses OAuth2 as the authentication and authorization framework. Your client application needs to follow the conventions outlined by the Internet Engineering Task Force’s OAuth2 Specification.

📘
Note
As you begin this process, you should have your client application open and ready so that you can copy and paste the client ID and secret for immediate testing.

Acquire CMP authorization information

You need the following information to get started.

Host – https://accounts.welcomesoftware.com
Authorization endpoint – https://accounts.welcomesoftware.com/o/oauth2/v1/auth
Scopes – openid, profile and offline_access (These scopes are delimited by a single space. All of these scopes must be passed to the authorization endpoint)
Token endpoint – https://accounts.welcomesoftware.com/o/oauth2/v1/token
Userinfo endpoint – (can be used to validate access token): https://accounts.welcomsoftware.com/o/oauth2/v1/userinfo

When you are ready for the client ID and secret in your application, you are ready to register your app with CMP. See Authentication to make sure your client application is ready for the registration process.

Obtain the Client ID and Secret to register your client application

📘
Prerequisite
You should be an administrator and (or have manage Integrations permissions in your role profile) because the first step requires you to register your client application so that you can receive your client ID and Secret.

Go to your avatar > Apps & Webhooks.
Click Register App and fill out the form.

Select Development or Production mode.
- Development – If you are developing a client application in a sandbox instance of Welcome, you could set the mode to Development to retain your authentication token for up to 30 days.
  - TTL for the access token – 30 days
  - Rate limit – 10 requests per second per organization
  - Request quota – 200,000 requests per month per organization
- Production – When you move your integration to a Production instance of CMP, make sure the mode is set to Production to ensure a more secure timeout.
  - TTL for the access token – 1 hour
  - Rate limit – 10 requests per second per organization
  - Request quota – 200,000 requests per month per organization
  - These modes cannot be changed after an application is registered. If you are making the transition from Development to Production, you can register a new application with the same settings.
Name – Enter a name.
Description – Enter a description.
Expose Email Address – If email is exposed, email addresses are visible to authorized API responses where applicable.
Homepage URL – Enter the value that represents your application’s homepage. This value represents a URL that can redirect the user if timeout or error conditions occur during the integration.
Authorization Callback URL’s – During the OAuth2 exchange, a server sends and receives responses to this authorization callback URL. Enter the URL which will receive the authorization requests from the CMP server. These URL’s should always begin with https:/.

Click Create App. The grid view of registered applications displays.
Click your application and click Edit. Two new fields display: The Client ID and Client Secret are generated for your application. Use the Copy feature to copy them into your application into the appropriate places. Keep these values safe. CMP stores these values in Apps and Webhooks if you need to access them again. If you need to re-generate the Client ID and Client Secret, you need to register a new application and follow these steps again.

Register OAuth 2.0 apps in CMP

To register an app, you will need to provide the following information

CMP Organization name – An app must be associated with a CMP organization. An app cannot be associated with multiple CMP organizations.
Redirect URL – A valid URL of the server hosting the web app where the CMP authorization server sends back the authorization code.
App name – A name for the app.

On successful registration, you receive a client_id and a client_secret from CMP with which you can request access_token and refresh_token from the CMP authorization server.

Authorization code flow

CMP supports only the authorization code flow for OAuth 2.0.

Opens the web app in browser. You must be registered with the organization with which the app is associated.
Perform some action (such as click a button) in the web app to begin the authorization process.

You are redirected to the authorization server.

HTTP GET
https://accounts.welcomesoftware.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
redirect_uri is the redirect url of the app provided when the app was registered

Authorization server logs the user in, if user is not logged in.
Through logging in, user gives the consent to the app to access the user's data from CMP.
User is 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.welcomesoftware.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) 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 Bearer prefix. For example.
```
HTTP GET
https://accounts.welcomesoftware.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 Bearer prefix. For example.

HTTP GET
https://api.welcomesoftware.com/v3/assets

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

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

HT
TP POST
https://accounts.welcomesoftware.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"
    }