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.
(Recommended) OAuth v2.0
Plaid expects your organization to secure the Plaid Exchange implementation using OAuth v2.0.
For more information, see the OAuth 2.0 specification and reach out to the Plaid team if you have any questions.
Alternative authentication methods
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,
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:
Alternative basic authentication
If your organization is unable to implement OAuth, then the following diagram shows a basic flow supported by Plaid.
For more information, see Authentication (
POST /users/auth_token) API Method.
Alternative multifactor authentication
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.
If the credentials are invalid, the partner can indicate the cause of the error see Authentication API reference.
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
Alternative authentication notes
If your organization is unable to implement OAuth, then see the following notes.
Plaid IP addresses and credentials
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:
|X-PLAID-CLIENT-ID||Pre-arranged client ID.||7aaaaaa9j6480121fx361|
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
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:
|X-PLAID-USER-ID||Partner-issued, opaque unique user ID.||54229637392405542503|
|X-PLAID-AUTH-TOKEN||Partner-issued, per-user revocable token||fHizq7w3qkauMYd1Z8vyDQ|
Neither user ID nor auth token should be derived from any information related to the user, e.g. the user’s social security number, phone number, or their account number in another online banking application. Specifically, if communicated to a malicious actor, this value must not provide exploitable information about the user’s identity or accounts in other applications or schemas.
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:
institution_id should be assigned to each of the institutions that the integration serves,
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.