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 registeredredirect_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 arefresh_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 theAuthorization
HTTP header withBearer
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 theAuthorization
HTTP header withBearer
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 newaccess_token
, using therefresh_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" }
Updated about 1 month ago