Authentication API Reference

The Plaid Authentication API provides a mechanism for integration partners to authenticate user attempts to connect accounts to Plaid apps. Successful authentication will return token-identifier pairs, which Plaid will subsequently use to refer to the user’s accounts. The API provides methods for the partner to refresh access tokens, as well as to revoke tokens unilaterally, and to communicate that revocation to Plaid.

Plaid will present two levels of authentication before requesting resources on behalf of the partner institution customers.

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.

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.

Plaid will present user credentials in exchange for an access token, which will be presented 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:

The authentication flow has one essential method, Authentication User Credentials, to which credentials are presented. If authentication is successful, the API returns a token and a principal identifier for the user. These are used in all subsequent requests to address and access the user’s authenticated resources.

1{
2  "username": "jane@doe.com",
3  "password": "keepyourpasswordsecret",
4  "institution_id": "ins_1"
5}

1{
2  "user_id": "YRQ8PPaohJ",
3  "auth_token": "1fce3854-0134-44ac-a1e1-d84ed09fec10"
4}

202 Accepted

This response indicates that Plaid must challenge the user according to one of two escalated authentication strategies: knowledge-based authentication (KBA) or one-time passcode. Describing these strategies is beyond the scope of this document, and the partner institution is presumed to understand how to choose the appropriate strategy for its user base.

A 202 Accepted response does not indicate that the presented credentials are correct.

Request orchestration

The next request in the KBA and TOTP authentication flows will be to Validate MFA API method, and in the OTP it will be to Trigger OTP API method.

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.

MfaEscalationChallengeType

MfaEscalationChallenge

1{
2  "id": "string",
3  "type": "otp"
4}

MfaEscalationChallengeResponse

1{
2  "user_id": "v5z37MvUF7",
3  "challenge": {
4    "id": "jOSsqir1tc",
5    "type": "kba",
6    "questions": [
7      {
8        "id": "Z9D0iK",
9        "text": "What city were you born in?"
10      },
11      {
12        "id": "ch7SbY",
13        "text": "Where did you go to high school?"
14      },
15      {
16        "id": "36b4Xo",
17        "text": "What is your mother's maiden name?"
18      }
19    ]
20  }
21}

MfaKbaQuestion

1{
2  "id": "string",
3  "text": "string"
4}

MfaTotpEscalationChallenge

1{
2  "type": "otp",
3  "prompt": "Open the XYZ app to receive your code.",
4  "id": "string"
5}

MfaOtpEscalationChallenge

1{
2  "id": "string",
3  "type": "otp",
4  "send_methods": [
5    {
6      "id": "Z9D0iK",
7      "mask": "(***) ***-8653",
8      "type": "sms"
9    },
10    {
11      "id": "36b4Xo",
12      "mask": "j****@p****.com",
13      "type": "email"
14    }
15  ]
16}

MfaOtpSendMethod

1{
2  "id": "string",
3  "mask": "(***) ***-8653",
4  "type": "sms"
5}

OtpSendMethodType

401 Unauthorized

The authentication credentials were rejected.

403 Forbidden

The user’s account is locked, typically due to excessive incorrect authentication attempts. This response will trigger messaging to the user indicating that the account has been temporarily locked, and will advise the user to contact the institution.

405 Not Allowed

This response should be used to indicate that the user’s account is not permitted to participate in aggregation, typically because the user must accept a license or terms of use. This will trigger messaging to the user indicating that the account is not yet authorized for online use, and will direct the user to visit the partner institution’s online portal for further guidance.

Plaid recommends that whatever pending terms or agreements that block this use case be presented to the user immediately upon login.

1{
2  "challenge_id": "jOSsqir1tc",
3  "send_method_id": "Z9D0iK"
4}

200 OK

This response indicates that the send method was acceptable and the partner institution will transmit the passcode to the user. No response body is required.

400 Bad Request

This response indicates that the send method was not acceptable.

Receive and authenticate the user’s response to the escalation challenge. This endpoint receives both KBA responses and (T)OTP passcodes in the form of ValidateChallengeRequest instances.

1{
2  "challenge_id": "jOSsqir1tc"
3}

1{
2  "passcode": "123456",
3  "challenge_id": "jOSsqir1tc"
4}

1{
2  "answers": [
3    {
4      "question_id": "Z9D0iK",
5      "text": "San Francisco"
6    }
7  ],
8  "challenge_id": "jOSsqir1tc"
9}

1{
2  "question_id": "Z9D0iK",
3  "text": "San Francisco"
4}

Plaid Exchange supports user authentication via redirection, utilizing a token exchange protocol compatible with OAuth.

1. The institution registers with Plaid an authentication URL. Plaid will redirect users to this URL to authenticate after they select an institution in Link.
2. Plaid will generate a URL with the following query parameters. institution_id is included to facilitate platforms that support more than one institution. application_id is to identify the Plaid client who is creating a connection.
   • state=<PLAID_GENERATED>
   • response_type=code
   • redirect_uri=<PLAID_GENERATED>
   • client_id=PLAID
   • institution_id=ins_<YOUR_INSTITUTION_ID>
   • application_id=<PLAID_APPLICATION_ID>
   • plaid_trusted_auth_token=<PLAID_GENERATED> (only present for Trusted Auth integrations)
3. The user is subsequently redirected, and completes authentication on the institution's domain. Prior to proceeding with authentication, the institution MUST verify that the redirect_uri query parameter has previously been registered to Plaid. See RFC 6749 Section 3.1.2.2.
   • On success, the institution redirects back to Plaid (via the redirect_uri) with the state and code query parameters. The code query parameter contains the authorization code granted by the institution.
   • On failure, the institution redirects back to Plaid (via the redirect_uri) with a state, error, and optional error_description query parameters.
   • In addition to the standard OAuth error codes, Plaid recommends the following error codes to deliver more granular errors to the consumer:
     • user_denied_access - used when the user has explicitly denied access.
     • user_exited - used when the user has clicked a button to exit the flow without accepting or denying.
   • See RFC 6749 Section 4.1.2
4. Subsequently, Plaid will exchange the supplied authorization code for a persistent access token using this endpoint. On success, this endpoint must return an auth_token as described in Token Management.
   • Plaid will authenticate itself via the X-PLAID-CLIENT-ID and X-PLAID-SECRET headers, as described in Plaid Authentication
   • This endpoint MUST verify Plaid's credentials.
   • The endpoint MAY verify that the request comes from one of Plaid's IP addresses, previously communicated to the financial institution.
   • The endpoint MUST ensure that the supplied authorization code was issued to Plaid.
   • The endpoint MUST ensure that the authorization code is valid.
   • The institution MAY implement a TTL on the authorization code, consistent with OAuth best practices.
   • The institution MUST verify that the redirect_uri is the same one sent in the initial authentication request.

1{
2  "state": "vEPcsYYKyf9iDfZnJZWjtZSJUiLr3JxE",
3  "response_type": "code",
4  "redirect_uri": "https://cdn.plaid.com/link/v2/stable/oauth.html",
5  "client_id": "PLAID",
6  "institution_id": "ins_1",
7  "application_id": "6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
8}

1{
2  "user_id": "YRQ8PPaohJ",
3  "auth_token": "1fce3854-0134-44ac-a1e1-d84ed09fec10"
4}

401 Unauthorized

The response was not accepted. Plaid will assume that the flow should be aborted and will prompt the user to retry.