Authentication API Reference
(Recommended) OAuth
Plaid expects that your organization secures your Plaid Exchange API implementation using an OAuth 2.0 server. For more information, see the API overview.
Alternative security endpoints
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:
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:
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
orTOTP
- KBA validation request: For
KBA
. If the validation is successful, this endpoint returns an authorization response with an auth token for the user.
- OTP validation request: For
- POST /users/{user_id}/sendOtp: Plaid sends this for
Request an auth token for a 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:
POST /users/auth_token
Provides Plaid a mechanism by which a credentials pair can be authenticated and exchanged for a user ID and access token authorized to request user-specific resources on behalf of the partner institution’s customer. This call may result in a 2-factor challenge.
users/auth_tokenRequest fields and example
username
password
institution_id
1curl --location --request POST2'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'
Responses
Successful responses include 200
for basic authentication and 202
for multifactor authentication.
200 OK
For basic authentication, POST users/auth_token
returns a 200 response with the access token:
Response fields and example
user_id
auth_token
1{2 "user_id": "YRQ8PPaohJ",3 "auth_token": "1fce3854-0134-44ac-a1e1-d84ed09fec10"4}
Was this helpful?
202 Accepted
For more information, see the following multifactor authentication section.
400 Bad Request
Response indicating the presence of an error.
request_id
error
Was this helpful?
401 Not Authorized
Response indicating the presence of an error.
request_id
error
Was this helpful?
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
Response indicating the presence of an error.
error
retry_at
date-time
id
message
request_id
Was this helpful?
Multifactor authentication
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 requestsPOST /users/{user_id}/sendOtp
thenPOST /users/{user_id}/2fa
.MfaKbaEscalationChallenge
for knowledge-based 2FA authentication. This indicates Plaid next requestsPOST /users/{user_id}/2fa
.MfaTotpEscalationChallenge
for temporary, on-hand password 2FA authentication. This indicates Plaid next requestsPOST /users/{user_id}/2fa
.
See the following sections for details.
202 response for OTP
If Plaid receives the MfaOtpEscalationChallenge
response (the most common scenario) from POST /users/auth_token
, Plaid:
- 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
orsms
. - 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. - after receiving a 200 response, prompts the user in Plaid Link to fill in the OTP and waits for them to fill it in.
- sends the OTP the user entered for validation using the
POST /users/{user_id}/2fa
request. For more information see Validate 2FA.
MfaOtpEscalationChallenge response
Prompts user to choose how to receive their out-of-band one-time passcode as part of an MFA escalation
user_id
challenge
id
type
fido2
otp
kba
push
totp
prompt
send_methods
1
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}
Was this helpful?
202 response for KBA
If Plaid receives the MfaKbaEscalationChallenge
response from POST /users/auth_token
, Plaid:
- prompts the user in Plaid Link to enter answers to the questions that Plaid received in the
MfaKbaEscalationChallenge
response. - sends the answers the user entered for validation using the
POST /users/{user_id}/2fa
request. For more information see Validate 2FA.
MfaKbaEscalationChallenge response
Questions the user must answer.
user_id
challenge
id
type
fido2
otp
kba
push
totp
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}
Was this helpful?
202 response for TOTP
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:
- prompts the user in Plaid Link to fill in the TOTP and waits for them to fill it in.
- sends the TOTP the user entered for validation using the
POST /users/{user_id}/2fa
request. For more information see Validate 2FA.
MfaTotpEscalationChallenge response
Prompts for a temporary password from an on-hand password generator.
user_id
challenge
type
fido2
otp
kba
push
totp
prompt
1{2 "user_id": "example_id",3 "challenge": {4 "id": "Adf2345",5 "type": "totp",6 "prompt": "Enter your one-time password."7 }8}
Was this helpful?
401 Unauthorized
Response indicating the presence of an error.
request_id
error
Was this helpful?
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.
Trigger OTP
POST /users/{user_id}/sendOtp
In the case of OTP authentication, provides Plaid with a mechanism to trigger partner-initiated delivery of OTP to the user’s selected send method.
users/{user_id}/sendOtpRequest fields and example
challenge_id
send_method_id
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' \
Responses
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
Response indicating the presence of an error.
request_id
error
Was this helpful?
503
Response indicating the presence of an error.
error
retry_at
date-time
id
message
request_id
Was this helpful?
Validate 2FA
POST /users/{user_id}/2fa
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.
Validate TOTP or OTP
ValidateOtpChallengeRequest
Request to validate TOTP or OTP code.
challenge_id
passcode
1{2 "passcode": "123456"3}
Was this helpful?
1curl --location --request POST2'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'
Validate KBA
ValidateKbaChallengeRequest
Request to validate KBA challenge answers.
challenge_id
answers
question_id
text
1{}
Was this helpful?
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
.
Response fields and example
user_id
auth_token
1{2 "user_id": "YRQ8PPaohJ",3 "auth_token": "1fce3854-0134-44ac-a1e1-d84ed09fec10"4}
Was this helpful?
400 Bad Request
Response indicating the presence of an error.
request_id
error
Was this helpful?
401 Not Authorized
Response indicating the presence of an error.
request_id
error
Was this helpful?
503
Response indicating the presence of an error.
error
retry_at
date-time
id
message
request_id