Plaid expects that your organization secures your Plaid Exchange API implementation using an OAuth 2.0 server. For more information, see the API overview.

OAuth is the preferred security method. However, if your team is unable to support OAuth, please work with the Plaid team on an alternate solution.

This API reference describes the following alternative security endpoints with the following workflow:

1. POST /users/auth_token: this endpoint is used for basic as well as multi-factor authentication.

   • For basic, it returns an authorization response with an auth token for the user.
   • For multifactor authentication flows, the endpoint responds with one of the following:
     • OTP challenge response
     • KBA challenge response
     • TOTP challenge response

2. Based on the multifactor challenge type, Plaid then calls one or both of the following:

   • POST /users/{user_id}/sendOtp: Plaid sends this for OTP flows only
   • POST /users/{user_id}/2fa For this endpoint, depending on the multi-factor authentication flow, Plaid sends one of the following:
     • OTP validation request: For OTP or TOTP
     • KBA validation request: For KBA. If the validation is successful, this endpoint returns an authorization response with an auth token for the user.

Plaid uses the POST /users/auth_token endpoint to request an auth token for a user. This endpoint is the essential API method for authenticating user credentials and is a part of all non-OAuth authentication flows documented here, including multifactor flows.

• For an overview of the basic flow of this endpoint, see Alternative basic authentication.
• For an example request and response, see the following section:

1curl  --location --request POST
2'https://your-institution.com/users/auth_token/' \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--header 'X-PLAID-CLIENT-ID: example_ID' \
5--header 'X-PLAID-SECRET: example_secret' \
6--header 'X-PLAID-VERSION: 2021-03-26' \
7--header 'Accept: application/json' \
8--data-urlencode 'username=user123&password=pass123&institution_id=inst123'

Successful responses include 200 for basic authentication and 202 for multifactor authentication.

For basic authentication, POST users/auth_token returns a 200 response with the access token:

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

202 Accepted

For more information, see the following multifactor authentication section.

400 Bad Request

401 Not Authorized

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.

503

If the response from POST /users/auth_token is 202 Accepted, then Plaid must challenge the user with a multifactor authentication flow.

The 202 response indicates that presented credentials are accepted for further processing. It does not indicate that the presented credentials are correct. For an overview of the multifactor authentication flow, see Alternative multifactor authentication.

The 202 response body is one of the following:

• MfaOtpEscalationChallenge for temporary, out-of-band password 2FA authentication. This indicates Plaid next requests POST /users/{user_id}/sendOtp then POST /users/{user_id}/2fa.
• MfaKbaEscalationChallenge for knowledge-based 2FA authentication. This indicates Plaid next requests POST /users/{user_id}/2fa.
• MfaTotpEscalationChallenge for temporary, on-hand password 2FA authentication. This indicates Plaid next requests POST /users/{user_id}/2fa.

See the following sections for details.

If Plaid receives the MfaOtpEscalationChallenge response (the most common scenario) from POST /users/auth_token, Plaid:

1. prompts the user in Plaid Link to select how they want their OTP sent, displaying the methods the partner indicates it supports in the MfaOtpEscalationChallenge response. For example, voice or sms.
2. sends the POST /users/{user_id}/sendOtp request indicating the partner should send the OTP to the user's selected method. For more information see Trigger OTP API method.
3. after receiving a 200 response, prompts the user in Plaid Link to fill in the OTP and waits for them to fill it in.
4. sends the OTP the user entered for validation using the POST /users/{user_id}/2fa request. For more information see Validate 2FA.

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

If Plaid receives the MfaKbaEscalationChallenge response from POST /users/auth_token, Plaid:

1. prompts the user in Plaid Link to enter answers to the questions that Plaid received in the MfaKbaEscalationChallenge response.
2. sends the answers the user entered for validation using the POST /users/{user_id}/2fa request. For more information see Validate 2FA.

1{
2  "user_id": "example_id",
3  "challenge": {
4    "id": "Adf2345",
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}

If Plaid receives the MfaTotpEscalationChallenge response from POST /users/auth_token, this indicates that the partner doesn't have to send a temporary password because the user already has the temporary password generator on hand, for example in the form of an authenticator app that displays a new passcode every 60 seconds. If Plaid receives this response, Plaid:

1. prompts the user in Plaid Link to fill in the TOTP and waits for them to fill it in.
2. sends the TOTP the user entered for validation using the POST /users/{user_id}/2fa request. For more information see Validate 2FA.

1{
2  "user_id": "example_id",
3  "challenge": {
4    "id": "Adf2345",
5    "type": "totp",
6    "prompt": "Enter your one-time password."
7  }
8}

401 Unauthorized

403 Forbidden

This response indicates 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 indicates 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.

1curl -X POST 'https://your-institution.com/users/example_user_id_1/sendOtp' \
2    --header'X-PLAID-CLIENT-ID: PLAID' \
3    --header 'X-PLAID-SECRET: example_secret' \
4    --header 'X-PLAID-VERSION: 2021-03-26' \
5    --header 'Accept: application/json'  \
6    --header 'Content-Type: application/x-www-form-urlencoded' \
7    --data-urlencode 'challenge_id=36b4Xo&send_method_id=Z9D0iK' \

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

503

POST /users/{user_id}/2fa receives and validates the user's response to the escalation challenge. This is the final endpoint Plaid request in all multi-factor flow types.

Plaid sends one of the following request bodies to this endpoint:

• ValidateOtpChallengeRequest
• ValidateKbaChallengeRequest

See the following sections for details.

ValidateOtpChallengeRequest

1

1curl  --location --request POST
2'https://your-institution.com/users/user123/2fa/' \
3--header 'Content-Type: application/x-www-form-urlencoded' \
4--header 'X-PLAID-CLIENT-ID: example_ID' \
5--header 'X-PLAID-SECRET: example_secret' \
6--header 'X-PLAID-VERSION: 2021-03-26' \
7--header 'Accept: application/json' \
8--data-urlencode 'passcode=123456&challenge_id=example_id'

ValidateKbaChallengeRequest

1

1curl  --location --request POST 'https://your-institution.com/users/user123/2fa/' \
2--header 'Content-Type: application/x-www-form-urlencoded' \
3--header 'X-PLAID-CLIENT-ID: example_ID' \
4--header 'X-PLAID-SECRET: example_secret' \
5--header 'X-PLAID-VERSION: 2021-03-26' \
6--header 'Accept: application/json' \
7--data-urlencode 'challenge_id=string' \
8--data-urlencode 'answers[0].question_id=string' \
9--data-urlencode 'answers[0].text=San Francisco' \
10--data-urlencode 'answers[1].question_id=string2' \
11--data-urlencode 'answers[1].text=Billings High School'

Responses

200 OK

The challenge response was correct. The partner returns the access token in the AuthenticationResponse.

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

400 Bad Request

401 Not Authorized

503