Authentication Overview

The Marketing Operations REST API uses OAuth authentication. Each API endpoint requires a valid access token (or a refresh token to generate a new access token). These tokens are automatically generated when a user logs in to the application.

This page covers the two types of integrations Marketing Operations supports:

  • Retrieving an Access Token Directly from Marketing Operations
    In this type of integration, a user interacts with Marketing Operations.
  • Retrieving an Access Token for Services and Daemons
    In this type of integration, a process runs without user interaction.

Note: Variables are shown in this format: [variable].

Tip: If you get a null response when hitting an API route, there’s a good chance your token has expired. When this occurs, best practice is to retrieve a new token using your refreshToken.

Retrieving an Access Token Directly from Marketing Operations

Step 1: Register the Client Application

Complete these steps in Marketing Operations.

  1. Point to System Administration, and click System Tools.
  2. In System Tools, point to Integration and click Registrations.
  3. Click New.
  4. Complete the fields.
    Note: The Client Secret field operates like a password. However, there is no way to retrieve it from system, so remember it, or store it safely.
  5. Click Save.

Step 2: Get the Authorization Code

Complete these steps in your web browser.

  1. Navigate to this URL: https://[CustomerURL]/api/oauth/authorize?client_id=[ClientId]&redirect_uri=https%3A%2F%2Fwww.microsoft.com (replacing CustomerURL, ClientID and redirect_uri value with the appropriate values for your site. Note that the redirect_url must be url encoded since it is a query string parameter).
  2. Log in to the site.
    When your credentials are validated, you are redirected to a URL that is a concatenation of the redirect URI you specified and the authorization code.
    Example: https://www.microsoft.com/?AuthorizationCode=DI3V7NK44I

Note: The authorization code is only valid for five minutes.

Step 3: Create a Base-64 Encoded Authorization Code

Complete this task in your web browser.

  • Go to https://www.base64encode.org/ and create a base64 encoded string of [ClientId]:[Secret].
    Note: The colon between [ClientID] and [Secret] is required.

Step 4: Get Authorization and Refresh Tokens

Complete these steps in Postman.

  1. Select POST.
  2. Enter this URL: https://[CustomerURL]/api/oauth/create-token.
  3. Click the Headers tab.
  4. Type these Key-Value pairs:
    • client-id : [ClientId]
    • authorization-code : [authorization code you obtained in Step 2: Get the Authorization Code]
    • content-type : application/Json
    • Authorization : Basic [Base64 encoded string you obtained in Step 3: Create a Base-64 Encoded Authorization Code]
  5. Click Send.
    An access token and refresh token are returned.

Note: By default, the access token lasts 10 minutes before needing a refresh. You can use the refresh token to generate new access tokens for 10 days. If you receive a 401 Unauthorized response from the API with a null response body, your access token has expired.

Step 5: Refresh an Access Token (Optional)

Access tokens are only valid for 10 minutes by default. Once a token expires, API calls return unauthorized 401 responses. The advantage of using this method is that it hides authentication information from the header. Complete these steps in Postman.

  1. Select POST.
  2. Enter this URL: https://[CustomerURL]/api/token.
  3. Click the Headers tab.
  4. Type these Key-Value pairs:
    • client-id : [ClientId]
    • content-type : application/Json
  5. Click the Body tab.
  6. Click raw.
  7. Type:
     {
       "refreshToken":"[refresh token returned in Step 4: Get Authorization and Refresh Tokens]"
     }
  8. Click Send.
    This returns a new access token that is good for 10 minutes

Retrieving an Access Token for Services and Daemons

Step 1: Register the Client Application

Complete these steps in Marketing Operations.

  1. Point to System Administration, and click System Tools.
  2. In System Tools, point to Integration and click Registrations.
  3. Click New.
  4. Complete the fields.
    Note: The Client Secret field operates like a password. However, there is no way to retrieve it from system, so remember it, or store it safely.
  5. Click Save.

Step 2: Generate a Native Token

Complete these steps in Marketing Operations.

  1. Log in as the user for whom you will create the token.
  2. On the toolbar, click the User button, and click User Token.

  1. Click Generate.

Step 3: Create a Base-64 Encoded Authorization Code

Complete this task in your web browser.

  • Go to https://www.base64encode.org/ and create a base64 encoded string of [UserName]:[UserToken].
    Note: The colon between [UserName] and [UserToken] is required.

Step 4: Get the Access Token and Refresh Token

Complete these steps in Postman.

  1. Enter this URL: https://[CustomerURL]/api/oauth/create-native-token.
  2. Click the Headers tab.
  3. Type these Key-Value pairs:
    • client-id : [ClientId]
    • content-type : application/Json
    • Authorization : Basic [Base64 encoded string you obtained in Step 3: Create a Base-64 Encoded Authorization Code]
  4. Click Send.
    An access token and refresh token are returned.

Note: By default, the access token lasts 10 minutes before needing a refresh. You can use the refresh token to generate new access tokens for 10 days.

Step 5: Refresh an Access Token

Note: This step is optional. The process can be handled programmatically from within the service. The advantage of using this method is that it hides authentication information from the header.

Complete these steps in Postman.

  1. Select POST.
  2. Enter this URL: https://[CustomerURL]/api/token.
  3. Click the Headers tab.
  4. Type these Key-Value pairs:
    • client-id : [ClientId]
    • content-type : application/Json
  5. Click the Body tab.
  6. Click raw.
  7. Type:
     {
       "refreshToken":"[refresh token returned in Step 4: Get the Access Token and Refresh Token]"
     }
  8. Click Send.
    This returns a new access token that is good for 10 minutes

Revoking Tokens

You can revoke all refresh tokens for a user at DELETE api/oauth/revoke/{userID}. This immediately expires all refresh tokens associated with the {userID}. This route returns an error if the API user does not have permission to access the route:

  • the API user must match the {userID} specified; OR
  • the API user must be a Security Administrator or System Administrator (to revoke the refresh tokens of a different user)

Integration API, Access Domain Right

When making calls into the REST API, you will only have access to read, create, and update records that the user you are using to authenticate with the REST API has access to. For security reasons, we do not allow users with the System Administration, Access domain right to read and edit any record in the system via the REST API as in the UI, as integrations that use a single service user to get or set data should not need to be system administrators.

In order to give you the ability to limit REST API users to have access to certain areas of the system but not require the service user to be on every access list for object records, we’ve created a new domain right called Integration API, Access. When using a user with this domain right to make call into the REST API, the user is not required to be on the access list for the records you are working with, but still does require the appropriate domain right. For example, if you grant a user the Integration API, Access and Activity, View domain rights, that user will be able to see all activity records in Aprimo regardless of whether the user is on the access list for each individual activity. If you remove the Integration API, Access domain right and leave the Activity, View domain right, the user must be on the activity view access list to see an activity record through the API. The Integration API, Access domain right is not required for a user to be able to access data via the API; it only serves as a way to bypass access lists typically used in service-style integrations.

The following Aprimo resources have Access Lists:

  • Activities
  • Programs
  • Funding Accounts
  • Markets
  • Plans
  • Offers