OAuth 2.0 API Integration Considerations

Keep these considerations in mind when using OAuth 2.0 API integrations.

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.

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.

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.

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.

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.

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.

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. Both user and server-to-server integrations can 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.

Business unit switching refers to signing out of one account or MID and logging in to a different one. Access tokens and refresh tokens act in the context of a single business unit. 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 Engagement app components, an app is an externally hosted app that is iframed into and launched using the dropdown app menu in the web interface. In a business unit switch, Marketing Cloud Engagement retrieves your app’s logout endpoint, logs the user out of the current business unit or MID, and then logs the user into the target business unit. 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.

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

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

Customers can use IP allowlisting. 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.

Multitenant AppExchange partners that use web app integrations must be prepared to construct their customers’ v2/token endpoint if your application's status is 'Published'. Your application receives the customer’s subdomain, or tssd, and an authorization code after the customer has authorized your application 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 Installed Packages.

Multi-tenant AppExchange apps use the same client ID and client secret for all of their customers. This capability is automatically enabled as part of the AppExchange app publishing and installation process.