OAuth 2.0 API Integration Considerations

Keep these considerations in mind when using OAuth 2.0 API integrations in Marketing Cloud Installed Packages with enhanced functionality.

OAuth 2.0 Uses Different Authentication Endpoints

For OAuth 2.0 integrations, you can request authorization codes and access tokens by appending only the v2/authorize or v2/token endpoints to the Authentication Base URI. You can’t use the legacy v1/requestToken endpoint to request tokens for OAuth 2.0 integrations.

Updates Take Five Minutes to Work

It can take up to five minutes before authorization codes, access tokens, and refresh tokens generated by the v2/authorize and v2/token endpoints incorporate any changes made to your API integration in Installed Packages.

Redirect URIs Have Specific Requirements

When determining which redirect URIs to use for a web app or public app integration, consider the following.

  • You can include up to 10 redirect URIs per integration.
  • Enter redirect URIs in plain text in Installed Packages. A redirect URI can’t be URL-encoded in Installed Packages.
  • You must encode redirect URIs in the v2/authorize request.
  • You must use plain text redirect URIs in the v2/token request.
  • Use https:// or native mobile app syntax.
  • Include a base domain in the redirect URI. For example: https://example.com.
  • You can't use wildcards in a redirect URI.
  • To test locally, use https://127.0.0.1:80/ as a redirect URL. You can’t use localhost. For example, https://localhost:80/ isn’t valid.

License Users to Use Your Web or Public App

To use the functionality of a package, a user must have a license to that package. For a package’s web or public app integration to work on behalf of a user, that user must have a license. For more information, review Manage Licensing for Installed Packages.

Enable Server-to-Server Integrations

Before a server-to-server integration can receive a token for a business unit, the integration must first be authorized to work on behalf of that business unit. Enable and disable a server-to-server integration to work on behalf of a business unit on the Access tab in Installed Packages.

Some Users Can’t Access Business Units That an Integration Can

Make sure that your app can handle 401 and 403 responses for users who do not have access to specific business units. Your integration can use the account_id parameter to switch business units. While your integration has access to a business unit, the end user might not have access.

Some Integrations Can’t Access Business Units That Users Can

Make sure that you can handle a 401 unauthorized response from the v2/token route when a user switches to a business unit that your integration isn’t enabled to work in. Marketing Cloud allows both users and server-to-server integrations to work in multiple business units. However, you might not have enabled your server-to-server integration to act on behalf of a particular business unit that an end user switches into.

Your App Must Switch Business Units When a User Switches Business Units

In Marketing Cloud, business unit switching is logging out of one account or MID and logging in to another account or MID. Marketing Cloud access tokens and refresh tokens act in the context of a single business unit. So if a user switches to a different business unit, your app must also switch into that business unit and retrieve new tokens.

Web apps and public apps must reinitiate the entire authorization code flow to ensure that the app receives access tokens. The access tokens represent the context of the user in a particular business unit.

For web apps and public apps that use Marketing Cloud app components, a Marketing Cloud app is an externally hosted app that is iframed into and launched via the Marketing Cloud dropdown app menu. During a business unit switch, Marketing Cloud GETs your app’s logout endpoint, logs the user out of Marketing Cloud, and then logs the user into the target Marketing Cloud business unit or MID. During this process, your app’s login endpoint is called again, and your app must reinitiate the full OAuth 2.0 authorization code flow and subsequent /v2/userinfo call, if applicable. So every time that your app’s login endpoint is called, ensure that the full OAuth 2.0 authorization code flow is completed so that your app has access tokens, which represent the context of the user in that business unit.

Refresh tokens are also specific to a single business unit. This concept applies if your web app or public app performs offline actions. If you need to perform offline actions in many business units, do one of the following.

  • Store a single refresh token for each user in each of the user’s business units.
  • Use the account_id parameter on the refresh token flow to get tokens in the context of whichever business unit you need.

For server-to-server integrations using client credentials flow, retrieve a token in the context of the target business unit by specifying the MID in the account_id parameter of your v2/token request.

User Sessions Can Be Revoked at Any Time

Make sure that your web or public app integration can handle 401 errors when using access tokens or refresh tokens. A user’s session can be revoked at any time because of a password reset or administration processes, such as when the user’s license is temporarily removed from the package in Installed Packages.

Legacy Integrations Can’t Use OAuth 2.0

Legacy integrations, which are created in legacy packages, must continue to use the legacy v1/requestToken endpoint to acquire an access token. Legacy integrations can’t use OAuth 2.0 authentication flows.

Userinfo Route Returns Sub-objects, Not a Flat Map

Parse a userinfo response as fully structured JSON rather than as a key-value map.

AppExchange Partners: Prepare for Customer IP Allowlisting

Customers can use IP allowlisting in their Marketing Cloud account. To reduce the possibility of a service disruption, we recommend that third-party applications, such as AppExchange and implementation partners, publish or communicate your service’s IP range to your customers so that they can add it to their own allowlist.

AppExchange Partners: Request Tokens on Your Customer’s Behalf

Multitenant AppExchange partners that use web app integrations with Marketing Cloud must be prepared to construct their customers’ v2/token endpoint if your application's status is 'Published'. Your application receives the customer’s Marketing Cloud subdomain, or tssd, and an authorization code after the customer has authorized your application by logging in to Marketing Cloud, as part of the authorization code grant type for web app integrations. When you request a token on the customer’s behalf, you must use the customer’s subdomain, or tssd, if your application's status is 'Published'. For applications with 'In Development' status, you can use the authentication base URI available on the API integration component in Marketing Cloud Installed Packages.

AppExchange Partners: Use the Same Client ID and Client Secret

Multi-tenant AppExchange apps use the same client ID and client secret for all of their customers. Marketing Cloud automatically enables this as part of the AppExchange app publishing and installation process.