Authentication Flow

This flow facilitates the creation of user-application connections via Plaid Link. It provides partners with a means to validate credentials, optionally escalate authentication by instructing Plaid to present additional authentication challenges, refresh access tokens, to revoke tokens unilaterally, and to communicate that revocation to Plaid.

Plaid expects your organization to secure the Plaid Exchange implementation using OAuth v2.0. If you don't yet have an identity provider for integrating with OAuth, Plaid recommends Okta, an industry leading independent identity provider with expertise onboarding data partners to OAuth integrations. To learn more, see the blog post about Plaid's partnership with Okta or contact dataconnectivity@plaid.com to get started with using Okta for Plaid Exchange.

1A user, within a Plaid app, selects the partner institution using Plaid Link

2Plaid uses the OAuth2 authorization code flow to acquire authorization from the end user, and redirects the user to login at the partner institution

3After the user grants consent, the partner returns an authorization code to Plaid

4Plaid uses the authorization code to request access and refresh tokens

5The partner returns the associated access and refresh tokens

6Plaid calls partner's customers/current endpoint. Plaid uses the access token as a bearer token for this and subsequent aggregation requests

7Partner returns a unique identifier associated with the customer

8Plaid makes a first aggregation request using the user ID

9The partner returns aggregation information

For more information, see the OAuth 2.0 specification and reach out to the Plaid team if you have any questions.

OAuth is the preferred security method. However, if your team is unable to support OAuth, you can integrate with Plaid by implementing an alternative authentication scheme.

This alternative is an authentication protocol that is secured by Plaid Link and the Plaid edge network. The protocol itself is simple because access to the API method is restrictive. The exchange of credentials is constrained to a small window of time. Plaid does not store credentials and will purge them from memory as soon as they are forwarded to the partner's API.

This alternative protocol includes one essential API method, Authentication (POST /users/auth_token) API Method, to which Plaid presents its credentials and the user's credentials. If authentication is successful, the API returns a token and a principal identifier for the user. Plaid uses these in all subsequent requests to address and access the user’s authenticated resources.

At a high level, this alternative protocol follows flows described in the following diagrams:

If your organization is unable to implement OAuth, then the following diagram shows a basic flow supported by Plaid.

1A user, within a Plaid app, selects the partner institution using Plaid Link, is prompted with a login form, and enters their credentials

2Plaid forwards the credentials directly to the partner API implementation and immediately purges them. The partner validates the credentials and returns an AuthorizationResponse. If the credentials are invalid, the partner can indicate the cause of the error. See Authentication API reference

3Plaid stores the access token provided in the AuthorizationResponse and returns a success condition to Link.

4Plaid uses the access token to begin aggregating the user’s accounts.

For more information, see Authentication (POST /users/auth_token) API Method.

If your organization is unable to implement OAuth and requires multifactor authentication, then Plaid supports a number of escalation methods. Implement a method according to your security policies.

1A user, within a Plaid app, selects the partner institution using Plaid Link, is prompted with a login form, and enters their credentials

2Plaid forwards the credentials directly to the partner API implementation and immediately purges them.

3Plaid stores the access token provided in the AuthorizationResponse and returns a success condition to Link.

4The partner validates the credentials and returns an MfaEscalationResponse. This response does not necessarily indicate that credentials were accepted.

5Plaid forwards the credentials directly to the partner API implementation and immediately purges them. The partner validates the credentials and returns an AuthorizationResponse
If the credentials are invalid, the partner can indicate the cause of the error see Authentication API reference.

6Plaid uses the access token to begin aggregating the user's accounts.

In exceptional situations, the flow may fail and be aborted. In that case, the end user may receive an error message and choose to restart the authentication attempt. The partner implementation must not expect the next request to be to this endpoint, because if the user has restarted the authentication flow, the next request would go to the Authentication API method and the implementation should expect a response to this endpoint.

For more information, see the API reference:

• Multifactor authentication
• Trigger OTP (POST /users/{user_id}/sendOtp) API Method
• Validate 2FA (POST /users/{user_id}/2fa) API Method

If your organization is unable to implement OAuth, then see the following notes.

Plaid will present its credentials to the partner institution to confirm that its requests are authentic and originate from Plaid. These parameters are present, and must be verified, on every request:

Additionally, Plaid will only issue requests from pre-arranged IP addresses. The implementer must deny network traffic not originating from these addresses.

Plaid will present user credentials in exchange for authorization response, which contains a user_id and an auth_token. Plaid will present these on subsequent resource requests. The partner institution must validate that the provided access token corresponds to the requested user.

All requests which require per-user authentication will have the following parameters present in the request headers:

Multi-institution identification

If a Plaid Exchange API implementation serves multiple institutions, it will be necessary for the integration to discriminate which institution a Plaid-originating request is targeting. The implementing partner is expected to make user identifiers globally unique across all institutions. A straightforward way to implement this is by prefixing user identifiers with the institution identifier.

Two API methods will communicate a pre-shared institution_id parameter, because they involve initial authentication, before unique user identifiers can be exchanged:

• Authentication API method
• Item Import API method

A unique institution_id should be assigned to each of the institutions that the integration serves, and those values should be shared with Plaid. Plaid will include the institution_id parameter on the above methods so that the integration can distinguish the institution that should be the target of a request.