OAuth 2.0 API Integration Considerations

Keep these considerations in mind when you use OAuth 2.0 API integrations with installed packages.

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 5 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 for a web apps and public app integrations must meet these requirements.

• An integration can include up to 10 redirect URIs.
• Enter redirect URIs in plain text in Installed Packages. Don’t URL-encode the URIs in Installed Packages.
• Encode redirect URIs in the v2/authorize request.
• 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.
• You can’t use wildcards in a redirect URI.
• To test locally, use https://127.0.0.1:80/ as a redirect URL. Don’t use localhost.

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 don’t have access to specific business units. Use the account_id parameter in your integration 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. It’s possible to configure a server-to-server integration where the ability to act on behalf of a particular business is disabled.

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 launched in an iFrame by using the dropdown app menu in the web interface. When you switch business units, 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. Make sure that the full OAuth 2.0 authorization code flow is completed whenever your app’s login endpoint is called so that your app has access tokens.

Refresh tokens are also specific to a single business unit. This concept applies if your web app or public app performs offline actions. To perform offline actions in several business units, complete one of these steps.

• 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 that use the client credentials flow, specify the MID in the account_id parameter of your v2/token request. This step ensures that the integration retrieves a token that has the context of the target business unit.

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.

To reduce the possibility of a service disruption, we recommend that third-party application providers, such as AppExchange and implementation partners, publish or communicate their service’s IP range to your customers so that customers can add it to their allowlists.

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.

Business Units that own packages must remain active for the app to continue working. If a business unit is deleted or deprecated, the packages created under that business unit fail the OAuth 2.0 authorization flow. To prevent service interruptions, make sure that all of the packages in a business unit are unused before you delete a business unit. After a business unit is deleted, it can’t be recovered.