OAuth Guide

OAuth is an industry-standard protocol for authenticating and permissioning data to third parties. With OAuth, end users can grant third parties access to their data without sharing their credentials directly with the third party.

Typically, end users authenticate and permission data directly within Plaid Link when connecting their financial accounts to third party applications. With OAuth, however, end users temporarily leave Link to authenticate and permission data using the institution's website or mobile app instead. Afterward, they're redirected back to Link to complete the Link flow and return control to the third party application.

In addition, Plaid integrations with OAuth have several benefits over the traditional, non-OAuth experience in Link, such as:

• Familiar and trustworthy experiences With OAuth, end users authenticate via the bank's website or mobile app, a familiar experience that can help with conversion.

• Streamlined login experiences Some OAuth-enabled institutions (e.g., Chase) provide an "App-to-App" experience for end users if the end user has the institution's mobile app installed on their device. App-to-App can provide alternative authentication methods to end users (e.g., Touch ID or Face ID) that can help simplify and accelerate the authentication process.

• Greater connection uptime You can generally expect greater connection uptime with OAuth-enabled institutions, which means fewer connection errors for end users when using Plaid Link.

• Longer-lived connections Items at OAuth-enabled institutions generally remain connected longer. This typically results in fewer re-authentication errors (e.g., ITEM_LOGIN_REQUIRED).

• Improved MFA (multi/second-factor) support OAuth-enabled institutions can support end user accounts that may be currently unsupported due to the end user's MFA settings.

Plaid supports the OAuth2 protocol. For a full list of Plaid integrations that use OAuth, call the /institutions/get endpoint with your desired country_codes and the oauth option set to true. The response for all institutions includes an oauth field, which indicates whether or not Plaid uses OAuth to authenticate users for that institution.

Some institutions are in the process of converting from non-OAuth flows to OAuth-based flows. These institutions will have multiple records available to institutions endpoints, with one representing the OAuth version of the institution and one representing the non-OAuth version.

OAuth requires the use of Link tokens. If you are using a legacy implementation with public keys rather than Link tokens, see the Link token migration guide.

Production access is a prerequisite for implementing OAuth. Plaid will contact you once your account has been enabled for Production.

Before implementing OAuth, be sure to complete the registration requirements in the Plaid Dashboard.

• Application display information – This is public information that end users of your application will see when managing connections between your application and their bank accounts, including during OAuth flows. This information helps end users understand what your application is and why it is requesting access, which can improve conversion. In addition, some US institutions require your profile to be completed and will not allow apps with an empty profile to access their OAuth implementations.

• Company information – Information about your company. This information is not shared with end users of your application and is only accessible to Plaid, members of your team, and financial institutions you register with.

• Plaid Master Services Agreement – Your latest contract with Plaid. If this is marked as incomplete, please reach out to your account manager for an updated version.

• Plaid security questionnaire – To continue ensuring the highest level of security for Plaid end users, we require that you complete a questionnaire about your company's risk and security practices before accessing bank APIs.

1. Create and register a redirect URI

2. Generate a Link token and configure it with your redirect URI

3. Reinitialize Link at your redirect URI

4. (If applicable) Wait for OAuth approval from Plaid, which can be tracked on the Institution Registration page

5. (If applicable) Migrate existing Items: If you already have an existing Plaid integration, and Plaid has informed you that you are required to implement OAuth for a given institution, you will receive an OAuth Migration Guide via email from Plaid. Refer to the guide for detailed instructions on migrating existing Items.

1. Handle Link OAuth events

2. Listen for consent expiration webhooks

3. Manage consent revocation

4. (Europe only) Enable QR Code authentication

After successfully completing the OAuth flow via their bank's website or app, you'll need to redirect the end user back to your application. This is accomplished with a redirect URI that you'll need to set up and configure accordingly depending on your client platform.

For desktop web, mobile web, or React, the redirect URI is typically the address of a blank web page you'll need to create and host. This web page will be used to allow the end user to resume and complete the Link flow after completing the OAuth flow on their bank's website or app. https://example.com/oauth-page.html is an example of a typical redirect URI. After creating your redirect URI, add it to the Allowed redirect URIs.

For iOS SDK or React Native (iOS), the redirect URI is typically the address of a blank web page you'll need to create and host. You'll need to configure an Apple App Association File to associate your redirect URI with your application. To enable App-to-App authentication flows, you'll need to register the redirect URI as an app link. Custom URI schemes are not supported; a proper universal link must be used.

Register your Android package by adding the Android package name(s) to the Allowed Android package names list. Plaid will automatically create your redirect URI and its contents based on your package name. When specifying a redirect URI in the following steps, you will use android_package_name.

To implement OAuth, you'll need to specify your redirect URI via the redirect_uri field when generating a Link token with /link/token/create (on Android, use the android_package_name parameter to provide your Android package name instead). Use this Link token to initialize Link.

If you're using Link in update mode, ensure you specify your redirect URI via the redirect_uri field (on Android, use the android_package_name parameter to provide your package name instead).

Do not use query parameters when specifying the redirect_uri. Make sure to specify the user.client_user_id.

1const request = {
2  user: {
3    // This should correspond to a unique id for the current user.
4    client_user_id: 'user-id',
5  },
6  client_name: 'Plaid Test App',
7  products: [Products.Transactions],
8  country_codes: [CountryCode.Us],
9  language: 'en',
10  webhook: 'https://sample-web-hook.com',
11  redirect_uri: 'https://example.com/callback',
12};
13
14try {
15  const createTokenResponse = await client.linkTokenCreate(request);
16  const linkToken = response.data.link_token;
17} catch (error) {
18  // handle error
19}

Using OAuth within an iFrame

Launching Link from within an iFrame is not recommended. If Link is launched from within an iFrame, you'll be unable to properly use redirect URIs or maintain user state. Page rendering, sizing, and data exchange may also be suboptimal when using some SDKs, like the JavaScript SDK.

If your application must launch Link from within an iFrame or from a webview within an app, then OAuth with redirect URIs will not function properly. In these particular cases, you can implement OAuth without configuring or specifying a redirect URI.

After completing the OAuth flow, the end user will be redirected to your redirect URI (e.g., https://example.com/oauth-page.html). This is where they'll resume and complete the Link flow and return to your application. To do this, you'll need to reinitialize Link at your redirect URI.

Depending on your client platform, Link may require additional configuration to work with OAuth. Detailed instructions for each platform are provided below.

For desktop web, mobile web, or React, you'll need to launch Link twice, once before the OAuth redirect (i.e., the first Link initialization) and once after the OAuth redirect (i.e., Link reinitialization). The Link reinitialization should occur at your redirect URI.

When reinitializing Link, configure it using the same Link token you used when initializing Link the first time. It is up to you to determine the best way to provide the correct link_token upon redirect. As an example, the code sample below demonstrates the use of a browser's local storage to retrieve the Link token from the first Link initialization.

1import React, { useEffect } from 'react';
2import { usePlaidLink } from 'react-plaid-link';
3
4const OAuthLink = () => {
5  // The Link token from the first Link initialization
6  const linkToken = localStorage.getItem('link_token');
7
8  const onSuccess = React.useCallback((public_token: string) => {
9    // send public_token to server, retrieve access_token and item_id
10    // return to "https://example.com" upon completion
11  });
12
13  const onExit = (err, metatdata) => {
14    // handle error...
15  };
16
17  const config: Parameters<typeof usePlaidLink>[0] = {
18    token: linkToken!,
19    receivedRedirectUri: window.location.href, //the redirect URI with an OAuth state ID parameter
20    onSuccess,
21    onExit,
22  };
23
24  const { open, ready, error } = usePlaidLink(config);
25
26  // automatically reinitialize Link
27  useEffect(() => {
28    if (ready) {
29      open();
30    }
31  }, [ready, open]);
32
33  return <></>;
34};
35
36export default OAuthLink;

In addition, when reinitializing Link, you should configure it with the receivedRedirectUri field and pass in the full received redirect URI, as demonstrated in the code sample. The received redirect URI is your redirect URI appended with an OAuth state ID parameter. The OAuth state ID parameter will allow you to persist user state when reinitializing Link, allowing the end user to resume the Link flow where they left off. No extra configuration or setup is needed to generate the received redirect URI. The received redirect URI is programmatically generated for you by Plaid after the end user authenticates on their bank's website or mobile app. You can retrieve it using window.location.href.

The received redirect URI must not contain any extra query parameters or fragments other than what is provided upon redirect. The standard Link callback onSuccess will be triggered as usual once the user completes the Link flow.

1https://example.com/oauth-page.html?oauth_state_id=9d5feadd-a873-43eb-97ba-422f35ce849b`

Optional methods for retrieving the initial Link token

If Link is reinitialized in the same browser session as the first Link initialization, you can store the Link token in a cookie or local storage in the browser for easy access when reinitializing Link. For example, the Plaid Quickstart uses localStorage.setItem to store the token.

If Link is reinitialized in a different browser session than the first Link initialization, you can store a mapping of the Link token associated with the user (server-side). Upon opening the second browser session, authenticate the user, fetch the corresponding Link token from the server, and use it to reinitialize Link.

For webview, you'll need to launch Link twice, once before the OAuth redirect (i.e., the first Link initialization) and once after the OAuth redirect (i.e., Link reinitialization). The Link reinitialization should occur at your redirect URI.

For the initial Link instance, first generate a Link token as described in Configure your Link token with your redirect URI, then set Link's token parameter to this Link token. After the end user successfully completes the OAuth flow via their bank's website or app, they'll be redirected to your redirect URI, where you'll reinitialize Link.

1https://cdn.plaid.com/link/v2/stable/link.html? isWebview=true
2&token=GENERATED_LINK_TOKEN

When reinitializing Link, use the same Link token you generated when you first initialized Link. It is up to you to determine the best way to provide the correct link_token upon redirect.

In addition, when reinitializing Link, you should configure it with the receivedRedirectUri field. The received redirect URI is your redirect URI appended with an OAuth state ID parameter. The OAuth state ID parameter will allow you to persist user state when reinitializing Link, allowing the end user to resume the Link flow where they left off. No extra configuration or setup is needed to generate the received redirect URI. The received redirect URI is programmatically generated after the end user authenticates on their bank's website or mobile app. The received redirect URI must not contain any extra query parameters or fragments other than what is provided upon redirect.

1https://cdn.plaid.com/link/v2/stable/link.html? isWebview=true
2&token=SAME_GENERATED_LINK_TOKEN&receivedRedirectUri=https://example.com/oauth-page?oauth_state_id=9d5feadd-a873-43eb-97ba-422f35ce849b

For the initial Link instance, first generate a Link token as described in Configure your Link token with your redirect URI. Your redirect_uri must also be added to the Plaid dashboard and should be configured as a universal link (not a custom URI) using an Apple App Association File.

1// With custom configuration
2let linkToken = "<#GENERATED_LINK_TOKEN#>"
3let onSuccess: (LinkSuccess) -> Void = { (success) in
4  // Read success.publicToken here
5  // Log/handle success.metadata here
6}
7let linkConfiguration = LinkTokenConfiguration(linkToken: linkToken, onSuccess: onSuccess)
8let handlerResult = Plaid.create(linkConfiguration)
9
10switch handlerResult {
11case .success(let handler):
12  self.handler = handler
13  handler.open(presentUsing: .viewController(self))
14case .failure(let error):
15  // Log and handle the error here.
16}

App-to-App OAuth requirements

During App-to-App OAuth, the end user is directed from your application to the bank's app to authenticate. To return the end user back to your application after they authenticate, your redirect URI must be a universal link. Once the user returns to your app, UIKit will invoke a method within your application and provide the redirect URI that triggered this return to the app.

The iOS SDK requires this redirect URI to be passed to its continue(from:) API in order to continue OAuth. Without this call, the SDK will not know whether the OAuth flow has completed and will therefore not update the UI. Add the following code to either your application delegate's func application(_:, continue:, restorationHandler:), or to your scene delegate's func scene(_:, continue:) function:

1if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let redirectUri = userActivity.webpageURL {
2  // NOTE: Your handler must be accessible from your application delegate or scene delegate.
3  self.handler.continue(from: redirectUri)
4}

If App-to-App does not function as intended, verify that the continue(from:) API is being called by setting a breakpoint on the function call. If the breakpoint is not hit, validate that the redirect URI used to configure Link is a valid universal link and that your application has the associated-domains entitlement for that URI.

When contacting Plaid Support for help with App-to-App OAuth issues, you may be asked to provide the value you pass to the continue(from:) API. This can be found by setting a breakpoint as described above, and logging the value of the parameter to LLDB (e.g. $ po redirectUri.absoluteString()).

React Native on iOS uses universal links for OAuth, and the following code is required in the AppDelegate in the native iOS code:

1- (BOOL)application:(UIApplication *)application
2continueUserActivity:(NSUserActivity *)userActivity
3  restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler
4{
5 return [RCTLinkingManager application:application
6                  continueUserActivity:userActivity
7                    restorationHandler:restorationHandler];
8}

This code block informs the React Native Linking library when the application is opened through a universal link. The React Native Plaid Link SDK will correctly continue OAuth when the application is opened through the registered universal link.

Handling universal links within React Native

The PlaidLink component handles Universal Links by default. For integrations that use PlaidLink.openLink, Universal Links will not be handled by default. The useDeepLinkRedirector hook must be invoked by the component that calls PlaidLink.openLink.

You won't need to reinitialize Link at a redirect URI when using Android SDK or Android on React Native, but you must generate a Link token by calling /link/token/create and passing in an android_package_name. Your package name (e.g., com.example.testapp) must also be added to the Plaid dashboard. Do not pass a redirect_uri into the /link/token/create call. Proceed to initialize Link with the generated token.

1String clientUserId = "user-id";
2
3LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser()
4  .clientUserId(clientUserId)
5  .legalName("legal name")
6  .phoneNumber("4155558888")
7  .emailAddress("email@address.com");
8
9LinkTokenCreateRequest request = new LinkTokenCreateRequest()
10  .user(user)
11  .clientName("Plaid Test App")
12  .products(Arrays.asList(Products.AUTH))
13  .countryCodes(Arrays.asList(CountryCode.US))
14  .language("en")
15  .webhook("https://example.com/webhook")
16  .linkCustomizationName("default")
17  .androidPackageName("com.plaid.example")
18
19Response<LinkTokenCreateResponse> response = client()
20  .linkTokenCreate(request)
21  .execute();
22
23String linkToken = response.body().getLinkToken();

You can test OAuth on Sandbox even if Plaid has not yet enabled OAuth flows for your account. To test out the OAuth flow in the Sandbox environment, you can use Platypus OAuth Bank (ins_127287). This dummy institution directs you to a Plaid sample OAuth flow that is similar to what you would see for a bank’s OAuth flow. When prompted, you can enter anything as credentials (including leaving the input fields blank) to proceed through the sample OAuth flow.

Unlike other Sandbox institutions, Platypus OAuth Bank does not support custom Sandbox data or programmatically creating Items via /sandbox/public_token/create.

You can also test two different types of OAuth flows in Sandbox and Development. By specifying a redirect_uri, the current page will be redirected to the bank's website. By omitting the redirect URI, the bank's website will open in a new window.

In Production, Link will select the type of OAuth flow that results in the best conversion regardless of the value of redirect_uri. It is still strongly recommended to specify a redirect_uri to support higher-converting App-to-App flows.

To ensure your OAuth integration works across all platforms, test it in the following scenarios before deployment:

• On each client platform that is available to your users (e.g. desktop, iOS app, iOS mobile web, Android app, Android mobile web)
• With the OAuth institution app installed, for institutions that support app-to-app authentication (e.g. Chase)
• Without the OAuth institution app installed
• In update mode, by using /sandbox/item/reset_login in the Sandbox environment

If your OAuth integration is not working correctly, check the following common configuration issues before contacting Support:

• Ensure your redirect URI is configured in the Plaid Dashboard
• For web, iOS SDK, or React Native iOS integrations, ensure the redirect_uri parameter is set in the /link/token/create call for all Link sessions, including Link in update mode
• For Android SDK integrations, ensure that your Android package name is registered in the Plaid Dashboard and that the android_package_name parameter is set in the /link/token/create call for all Link sessions, including Link in update mode
• For iOS SDK integrations, check that the redirect URI has been associated with an Apple App Association file, that your application has the associated-domains entitlement for that URI, and that you are calling continue(from:) in your application
• For React Native integrations, check the above for iOS and Android and ensure you are using the useDeepLinkRedirector hook

OAuth flows have a different sequence of Link events than non-OAuth flows. If you plan to track Link events to measure conversion or other metrics, you may need to handle these events differently for OAuth.

The sequence of Link callback events will look a little different from non-OAuth flows.

1OPEN (view_name = CONSENT)
2TRANSITION_VIEW view_name = SELECT_INSTITUTION)
3SELECT_INSTITUTION
4TRANSITION_VIEW (view_name = CREDENTIAL)
5SUBMIT_CREDENTIALS
6TRANSITION_VIEW (view_name = LOADING)
7TRANSITION_VIEW (view_name = MFA, mfa_type = device)
8SUBMIT_MFA (mfa_type = device)
9TRANSITION_VIEW (view_name = LOADING)
10TRANSITION_VIEW (view_name = MFA, mfa_type = code)
11SUBMIT_MFA (mfa_type = code)
12TRANSITION_VIEW (view_name = LOADING)
13TRANSITION_VIEW (view_name = CONNECTED)
14HANDOFF
15onSuccess

1OPEN (view_name = CONSENT)
2TRANSITION_VIEW (view_name = SELECT_INSTITUTION)
3SELECT_INSTITUTION
4OPEN_OAUTH
5TRANSITION_VIEW (view_name = CONNECTED)
6HANDOFF
7onSuccess

If the user closes the bank's OAuth window without completing the OAuth flow, Link will emit a CLOSE_OAUTH event.

If Plaid encounters an error from the bank's OAuth flow, or if the user chooses to not grant access via their OAuth login attempt, Link will emit the following events once the user returns to Link:

1FAIL_OAUTH
2TRANSITION_VIEW (view_name = ERROR, error = null)

Once you receive the onSuccess callback from an OAuth flow, the integration steps going forward are the same as for non-OAuth flows.

Some institutions require users to periodically re-affirm their consent to avoid Item expiration. When using OAuth, end users may need to refresh their access-consent after a certain amount of time.

To determine when a user will need to re-authenticate, make a request to the /item/get endpoint and note the consent_expiration_time field. Plaid will also send a PENDING_EXPIRATION webhook one week before a user’s access-consent is set to expire. In order to continue receiving data for that user, ensure they re-authenticate via update mode prior to that date. When using Link in update mode, be sure to specify your redirect URI via the redirect_uri field as described in Configure your Link token with your redirect URI.

Many institutions that support OAuth provide a means for the end user to revoke consent via their website. If an end user revokes consent, the Item will enter an ITEM_LOGIN_REQUIRED state after approximately 24-48 hours. We recommend giving the user an opportunity to either verify that they intended to remove the Item or to indicate that they did not mean to revoke access. If the user verifies that they meant to remove the Item or does not respond after a few days, delete the Item and associated data. If the user did not mean to revoke access, they can re-authorize access by going through the standard update mode flow.

Institutions that support OAuth may also provide the end user the ability to revoke consent for a single account, without revoking consent for the entire Item. Accounts in this situation are treated the same as accounts that have been closed: no webhook will be fired, you will stop receiving transactions associated with the account, and Plaid will stop returning the account in API responses. Access can be re-authorized via the update mode flow.

When using Link in update mode (for either case described in this section), be sure to specify your redirect URI via the redirect_uri field as described in Configure your Link token with your redirect URI.

OAuth can provide the ability for end users to configure granular permissions on their Items. For example, an end user may allow access to a checking account but not a credit card account behind the same login, or may allow an institution to share only certain account information, such as identity data but not transaction history. If an end user chooses not to share data that is required by your Link token's products configuration, or does not share access to any accounts, the Link attempt will fail. In this case, they will need to restart the Link flow.

Note that if your app calls /link/token/create using an account_filter parameter to limit the account types that can be used with Link, the filter will only be applied after the OAuth flow has been completed and will not affect the permission selection interface within the OAuth flow.

If your app later needs to request access to a product or account that was not originally granted for that Item during Link, you can send the user to the update mode flow to authorize additional permissions. When using Link in update mode, be sure to specify your redirect URI via the redirect_uri field as described in Configure your Link token with your redirect URI.

Some banks (e.g. Chase) support an App-to-App experience if the user is authenticating on their mobile device and has the bank's app installed. Instead of logging in via the bank's site, the bank's app will be launched instead, from which the user will be able to log in (including via TouchID or Face ID) before being redirected back to your app. Support for App-to-App should be automatic once you have implemented support for OAuth on mobile. Note that on iOS, this requires configuring an Apple App Association file to associate your redirect URI with your app, as described under Create and register a redirect URI.

The full App-to-App flow cannot currently be tested in the Sandbox environment. You can test that your universal link works correctly by opening it from another app (e.g. Safari, Chrome, Slack, Notes).

For many European institutions, Plaid supports the ability for an end user to authenticate via their bank's mobile app – even if the user's journey begins in a desktop-based web session – in order to optimize for conversion. After the user selects an institution, they will be presented with the choice to scan a QR code and authenticate in the bank’s mobile app or to continue on desktop. When the user scans the QR code, they will be redirected to the bank’s app (or website, if the user does not have the app installed). After the user completes the OAuth flow, they will be redirected to a Plaid-owned page instructing them to return to their desktop to complete the flow.

To enable QR authentication, contact your Plaid account manager or file a Support ticket. No changes to your Link OAuth implementation are required to enable this flow.

To test out the QR code flow in the Sandbox environment, you can use Flexible Platypus Open Banking (ins_117181). When you launch Link with this institution selected in Sandbox, the QR code authentication flow will be triggered. The Sandbox institution does not direct you to a real bank's mobile app, but allows you to grant, deny, or simulate errors from the placeholder OAuth page instead.