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. Aprimo Authorization should not be used anymore. Please plan around using our OAuth2.0 flows. If your integration already uses Aprimo Authorization please see this documentation.

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.

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.

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.

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.
  • Authorization Code (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 old, now deprecated, authorization 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.

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

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.

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