Link overview

Plaid Link is the client-side component that your users will interact with in order to link their accounts to Plaid and allow you to access their accounts via the Plaid API.

Plaid Link handles all aspects of the login and authentication experience, including credential validation, multi-factor authentication, error handling, and sending account linking confirmation emails. For institutions that use OAuth, Link also manages the OAuth handoff flow, bringing the user to their institution to log in, and then returning them to the Plaid Link experience within your app. Link is supported via SDKs for all modern browsers and platforms, including web, iOS, Android, as well as via React Native, along with community-supported wrappers for Flutter, Angular, and Vue.

For webview-based integrations or integrations that don't have a frontend, Plaid also provides a drop-in Hosted Link integration mode.

To try Link, see Plaid Link Demo.

Link is the only available method for connecting accounts in Production and is mandatory for all Plaid integrations. In the Sandbox test environment, Link can optionally be bypassed for testing purposes via /sandbox/public_token/create.

Link is initialized by passing the link_token to Link. The exact implementation details for passing the link_token will vary by platform. For detailed instructions, see the page for your specific platform: web, iOS, Android, React Native, mobile webview, or Plaid-hosted.

For recommendations on configuring the link_token for your use case, see Choosing how to initialize products.

Most Plaid products use Link to generate public_tokens. The diagram below shows a model of how Link is used to obtain a public_token, which can then be exchanged for an access_token, which is used to authenticate requests to the Plaid API.

Note that some products (Identity Verification, Monitor, Document Income, and Payroll Income) do not use a public_token or access_token. For those products, you will call product endpoints once the end user has completed Link; see product-specific documentation for details on the flow.

The Plaid flow begins when your user wants to connect their bank account to your app.

1Call /link/token/create to create a link_token and pass the temporary token to your app's client.

2Use the link_token to open Link for your user. In the onSuccess callback, Link will provide a temporary public_token. This token can also be obtained on the backend via `/link/token/get`.

3Call /item/public_token/exchange to exchange the public_token for a permanent access_token and item_id for the new Item.

4Store the access_token and use it to make product requests for your user's Item.

In code, this flow is initiated by creating a link_token and using it to initialize Link. The link_token can be configured with the Plaid products you will be using and the countries you will need to support.

Once the user has logged in via Link, Link will issue a public_token. You can obtain the public_token through either the frontend or the backend:

• On the frontend: From the client-side onSuccess callback returned by Link after a successful session. For more details on this method, see the Link frontend documentation for your specific platform.
• On the backend: From the /link/token/get endpoint or opt-in SESSION_FINISHED webhook after the Link session has been completed successfully. For more details on this method, see the Hosted Link documentation.

The public_token can then be exchanged for an access_token via /item/public_token/exchange.

Some institutions use an OAuth authentication flow, in which Plaid Link redirects the end user to their bank's website or mobile app to authenticate. To learn how to connect to an institution that uses OAuth, see the OAuth guide.

You can customize parts of Link's flow, including some text elements, the institution select view, and the background color, and enable additional features like the Account Select view straight from the Dashboard. You can preview your changes in realtime and then publish them instantly once you're ready to go live. For more details, see Link customization.

To help you take advantage of the options available for customizing and configuring Link, Plaid offers a best practices guide with recommendations for how to initialize and configure Link within your app.

Link's appearance will also automatically change if the institution selected is not in a healthy state. For more details, see Institution status in Link.

The returning user flow allows you to enable a faster Plaid Link experience for your users who already use Plaid. To learn more, see Returning user experience.

If your application will access an Item on a recurring basis, rather than just once, it should support update mode. Update mode allows you to refresh an Item if it enters an error state, such as when a user changes their password or MFA information. For more information, see Updating an Item.

It's also recommended to have special handling for when a user attempts to link the same Item twice. Requesting access tokens for duplicate Items can lead to higher bills and end-user confusion. To learn more, see preventing duplicate Items.

Occasionally, Link itself can enter an error state if the user takes over 30 minutes to complete the Link process. For information on handling this flow, see Handling invalid Link tokens.

How you configure Link can have a huge impact on the percentage of users who successfully complete the Link flow. To ensure you're maximizing conversion, see Best practices for Link conversion.

Since all your users will go through Link, it's important to build as robust an integration as possible. For details on dealing with common problems, see the Troubleshooting section.

Plaid periodically updates Link to add new functionality and improve conversion. These changes will be automatically deployed. Any test suites and business logic in your app should be robust to the possibility of changes to the user-facing Link flow.

Users of Plaid's SDKs for React, React Native, iOS, and Android should regularly update to ensure support for the latest client platforms and Plaid functionality.