Authorization

There are two major types of authorization supported by Aprimo.

• OAuth 2.0 Supported flows, including resource owner password flow, client credentials flow, and the interactive authorization code flow, and authorization code with PKCE flow.
• Aprimo Authorization, oauth-like flows similar to the resource owner password flow and interactive authorization code flow.

OAuth 2.0 token are supported by the Marketing Operations REST API, the DAM REST API, the DAM upload service, and the Reporting API. 

OAuth 2.0 tokens are currently not supported by the DAM PowerShell script for File Uploads, so please leverage the Aprimo Authorization flow instead.

It is recommended to use the OAuth 2.0 flows, as they are an industry standard, however, Aprimo Authorization flows will continue to function.

If you are using OAuth 2.0 flows, there are three options:

• Authorization Code with PKCE flow, allowing users to have an interactive web authorization flow with Aprimo.
• Client Credentials Flow, allowing a service to authorize as a specific user specified on the integration registration.
• Resource Owner Password Flow, allowing users to use their Aprimo username plus a user token retrieved from within Aprimo to get an access token.

If retrieving an OAuth 2.0 token, it must be supplied in an Authorization: Bearer [token] header for the MO REST API, DAM REST API, or Reporting API.

If you are using Aprimo Authorization flows, there are two options:

• Retrieving an Access Token Directly from Marketing Operations
  In this type of integration, a user interacts with Marketing Operations similar to an OAuth 2.0 authorization code flow.
• Retrieving an Access Token for Services and Daemons
  In this type of integration, a process runs without user interaction to retrieve a token from Aprimo, similar to an OAuth 2.0 resource owner password flow.

If retrieving an Aprimo Authorization token, it must be supplied in an Authorization: Bearer [token] header for the DAM REST API, an X-Access-Token: [token] header for the MO REST API, and is not supported for the Reporting API.

In order to create any kind of integration registration, you must have the Security Administration and/or System Administration domain rights.

All Aprimo access tokens have a 5 minute clock skew feature to avoid problems where tokens are not yet valid when they should be.

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

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

Before you can begin getting an access token you will need to register an Aprimo Client Registration. This is done in System Tools > Integration > Registrations. A few decisions need to be made when creating this client registration

• Client Name – The name of the client registration.
• Description – Description of what this registration will be used for.
• Client Secret – The secret. This can not be changed and should be stored in a secure manner.
• Redirect URL – The redirect URL of your client. This is required but will only be used if you use the Authorization Code flow
• OAuth Flow Type
  • None
  • Authorization Code(Obsolete)– This is not recommended and is only supported for existing integrations. If you need an interactive auth flow you should use PKCE.
  • Client Credentials
  • Resource Owner Password

Selecting ‘None’ for the OAuth Flow Type will disable usage of OAuth 2.0 flows and your integration will instead need to use Aprimo’s Getting a token directly from Marketing Operations flow.

• Client Credentials should be used when you need to make API calls as a service user only that does not need to be changed.
• Resource Owner Password should be used when you need to make API calls as multiple users, and you cannot open a browser window to have a user engage in a login flow.
• Authorization Code with PKCE should be used for individual user authorization where a user can go through a browser-based login flow to retrieve access and refresh tokens specific to individual users.

Scopes available:

• The api scope will allow you to invoke the REST API.
• The reporting-api scope will allow you to invoke the Reporting API.
• The offline_access scope will allow you to get a refresh token using the authorization code flow.
• The filestore-access scope will allows OAuth2.0 tokens to download attachment and digital asset files from Productivity Management.

Multiple scopes must be space separated e.g. {“scope”: “api offline_access”}

The authorization code flow allows you to retrieve an API token via an interactive web login with Aprimo, allowing you to have easier user-to-user level mapping between your application and Aprimo. In order to receive a refresh token, be sure to check the ‘Enable Refresh Token’ on the integration registration page when creating a registration.

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, setting the OAuth Flow Type to Authorization Code.
   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. Optionally, check the box that allows a refresh token to be returned, and set the refresh token life. Token life can be set to a minimum of 60 minutes, and a maximum of 10 days (14,400 minutes). Check the scopes section above – an additional scope will also have to be requested to be granted a refresh token.
6. Click Save.

Note that registrations are cached for a period of up to 15 minutes, so any changes may not take effect immediately.

Step 2: Prompt the user to login to Aprimo

Launch a browser window for the user to the following URL structure, replacing anything in brackets with your value (i.e. state=12345)
https://TENANT.aprimo.com/login/connect/authorize?response_type=code&state=[yourstate]&client_id=[yourclientid]&redirect_uri=[yourURLEncodedRedirectURI]&scope=[yourscopes]
Set State to a value you store on your end to validate on the callback to your redirect uri.
Your redirect URI must match the redirect URI supplied in the integration registration exactly.

Step 3: Retrieving an access token

Once the user has performed their authorization, either via an Aprimo login screen or their SSO provider, your redirect URI will be invoked as such:
https://your_redirect_uri?code=[onetimeusecode]&scope=[yourscope]&state=[yourstate]

Use the state to match to the flow started from your application.

Make an HTTP Request, posting to the URL https://[TENANT].aprimo.com/login/connect/token
Content-Type must be set to application/x-www-form-urlencoded

The request body must be as shown, replacing anything in brackets with your value (i.e. code=jxyz)

grant_type=authorization_code&code=[codePassedBackToYou]&redirect_uri=[yourUrlEncodedRedirectURI]&client_id=[yourClientId]&client_secret=[yourClientSecret]

An access and refresh token will be returned.

Once you have a refresh token you can use it to get a new access token.

Make an HTTP POST Request, posting to the URL https://[TENANT].aprimo.com/login/connect/token
Authorization header must be set to the base64 encoded version of “[yourClientId]:[yourClientSecret]”
Content-Type header must be set to application/x-www-form-urlencoded

The request body must be as shown, replacing anything in brackets with your value (i.e. code=jxyz)

grant_type=refresh_token&refresh_token=[yourRefreshToken]

This will return a new access token, a new refresh token, and invalidate the previous refresh token.

The authorization code with PKCE flow allows you to retrieve an API token via an interactive web login with Aprimo, allowing you to have easier user-to-user level mapping between your application and Aprimo. In order to receive a refresh token, be sure to check the ‘Enable Refresh Token’ on the integration registration page when creating a registration.

To learn more about PKCE check out this blog post as well as the RFC7636. When making a request for an access token you will need to generate a code verifier. This is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long. Using that code verifier you will need to create a code challenge. The code challenge is a Base64-URL-encoded string of the SHA256 hash of the code verifier.

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, setting the OAuth Flow Type to Authorization Code with PKCE.
   Note: The Client Secret field operates like a password. However, there is no way to retrieve it from system so store it safely.
5. Optionally, check the box that allows a refresh token to be returned, and set the refresh token life. Token life can be set to a minimum of 60 minutes, and a maximum of 10 days (14,400 minutes). Check the scopes section above – an additional scope will also have to be requested to be granted a refresh token.
6. Click Save.

Note that registrations are cached for a period of up to 15 minutes, so any changes may not take effect immediately.

Step 2: Prompt the user to login to Aprimo

Launch a browser window for the user to the following URL structure, replacing anything in brackets with your value (i.e. state=12345)

https://[aprimoEnvironment].aprimo.com/login/connect/authorize?
response_type=code
&state=[yourstate]
&client_id=[yourclientid]
&redirect_uri=[yourURLEncodedRedirectURI]
&scope=[yourscopes]
&code_challenge=[yourCodeChallenge]
&code_challenge_method=S265

Set State to a value you store on your end to validate on the callback to your redirect uri.
Your redirect URI must match the redirect URI supplied in the integration registration exactly.

Step 3: Retrieving an access token

Once the user has performed their authorization, either via an Aprimo login screen or their SSO provider, your redirect URI will be invoked as such:
https://your_redirect_uri?code=[onetimeusecode]&scope=[yourscope]&state=[yourstate]

Use the state to match to the flow started from your application.

Make the below HTTP Request. The request body must be as shown, replacing anything in brackets with your value (i.e. code=jxyz)

https://[aprimoEnvironment].aprimo.com/login/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=[codePassedBackToYou]
&redirect_uri=[yourUrlEncodedRedirectURI]
&client_id=[yourClientId]
&code_verifier=[yourCodeVerifier]
&client_secret=[yourClientSecret]

An access and refresh token(optional) will be returned.

The client credentials flow allows you to retrieve an API token from a backend service. The token returned will make always calls in the context of the user specified on the integration registration.

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, setting the OAuth Flow Type to Client Credentials, then set the User field to the user to make calls on behalf of. This is the only user that will be used for this registration.
   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. The Access Token Lifetime(minutes) field has a minimum value of 1 and a maximum value of 60.
5. Click Save.

Note that registrations are cached for a period of up to 15 minutes, so any changes may not take effect immediately.

Step 2: Retrieve an access token

Make an HTTP Request, posting to the URL https://[TENANT].aprimo.com/login/connect/token
Content-Type must be set to application/x-www-form-urlencoded

The request body must be as shown, replacing anything in brackets with your value (i.e. username=jdoe)

grant_type=client_credentials&scope=[yourScopes]&client_id=[yourClientId]&client_secret=[yourClientSecret]

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, setting the OAuth Flow Type to Resource Owner Password. The Access Token Lifetime(minutes) field has a minimum value of 1 and a maximum value of 60.
   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.

Note that registrations are cached for a period of up to 15 minutes, so any changes may not take effect immediately.

Step 2: Retrieve an access token

Make an HTTP Request, posting to the URL https://[TENANT].aprimo.com/login/connect/token
Content-Type must be set to application/x-www-form-urlencoded

The request body must be as shown, replacing anything in brackets with your value (i.e. username=jdoe)

grant_type=password&username=[yourUsername]&password=[yourUsertoken]&scope=[yourScopes]&client_id=[yourClientId]&client_secret=[yourClientSecret]

The UserToken can be retrieved from the Marketing Operations UI under your user menu->user token, or from the DAM UI (please contact support if you do not see this and need it, as a system setting may have to be changed).

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, setting the OAuth Flow Type to < None >.
   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 7 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

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, setting the OAuth Flow Type to < None >.
   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.

3. 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 7 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

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)

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