Plaid logo
Exchange
ALL DOCS

API reference

  • Authentication
  • Aggregation
  • Notification
  • Errors and Conditions
Open nav
Exchange
Plaid.comGet Started

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:

  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.

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_token

Request fields and example

username
requiredstring
Submitted username.
password
requiredstring
Submitted password.
institution_id
string
Institution identifier for partners with multiple institutions.
Copy
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'
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:

users/auth_token

Response fields and example

user_id
requiredstring
Opaque user identifier.
auth_token
requiredstring
Opaque, revocable token.
Copy
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
string
Unique identifier useful for tracing this request, when debugging.
error
requiredobject
Generic error object.
id
string
Opaque identifier, expected to be consistent for errors which have the same cause.
message
string
Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.
Was this helpful?
401 Not Authorized

Response indicating the presence of an error.

request_id
string
Unique identifier useful for tracing this request, when debugging.
error
requiredobject
Generic error object.
id
string
Opaque identifier, expected to be consistent for errors which have the same cause.
message
string
Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.
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

Signifying the institution is currently unavailable to respond to the request.

error
requiredobject
Generic error object.
retry_at
string
The time, in UTC, when the institution is expected to support aggregation again.

Format: date-time
id
string
Opaque identifier, expected to be consistent for errors which have the same cause.
message
string
Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.
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 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.

202 response for OTP

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.
MfaOtpEscalationChallenge response

Prompts user to choose how to receive their out-of-band one-time passcode as part of an MFA escalation

user_id
requiredstring
Opaque user identifier.
challenge
requiredobject
Contains the prompt and send methods for the OTP.
id
Unique identifier for this escalation flow instance. Enables correlation of challenges with responses, preventing attackers from gaining leverage by spamming.
type
Type of MFA escalation.
fido2
string
Cryptographic authenticator, via FIDO2.
otp
string
One-time passcode. The partner delivers this out of band from this API, for example through email or voice.
kba
string
Knowledge-based authentication, question/response-based challenge method.
push
string
Coordinated push notification, requiring acknowledgement.
totp
string
Time-based one-time passcode. The user accesses this code through on-hand devices, for example, an authenticator app that displays a new passcode every 60 seconds.
prompt
string
The text prompting users for the passcode. Plaid will relay the user's locale using the Accept-Language header. If the partner doesn't provide this text, Plaid falls back to its own prompt wording.
send_methods
[object]
For OTP flows, a list of delivery descriptions for out-of-band delivery of the passcode.

Min items: 1
id
string
An ID uniquely referencing this send method, for this user.
mask
string
A display-safe string that is evocative of this send method. An attacker should not gain an advantage if given this mask.
type
string
Indicates the method of delivery.

Possible values: sms, email, voice
Copy
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:

  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.
MfaKbaEscalationChallenge response

Questions the user must answer.

user_id
requiredstring
Opaque user identifier.
challenge
requiredobject
Contains knowledge-based challenge questions.
id
Unique identifier for this escalation flow instance. Enables correlation of challenges with responses, preventing attackers from gaining leverage by spamming.
type
Type of MFA escalation.
fido2
string
Cryptographic authenticator, via FIDO2.
otp
string
One-time passcode. The partner delivers this out of band from this API, for example through email or voice.
kba
string
Knowledge-based authentication, question/response-based challenge method.
push
string
Coordinated push notification, requiring acknowledgement.
totp
string
Time-based one-time passcode. The user accesses this code through on-hand devices, for example, an authenticator app that displays a new passcode every 60 seconds.
questions
[object]
The set of challenge questions.

Min items: 1
id
string
Unique identified for this question. Enables correlation of questions with submitted responses.
text
string
Text of the question.
Copy
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:

  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.
MfaTotpEscalationChallenge response

Prompts for a temporary password from an on-hand password generator.

user_id
requiredstring
Opaque user identifier.
challenge
requiredobject
The prompt
type
Type of MFA escalation.
fido2
string
Cryptographic authenticator, via FIDO2.
otp
string
One-time passcode. The partner delivers this out of band from this API, for example through email or voice.
kba
string
Knowledge-based authentication, question/response-based challenge method.
push
string
Coordinated push notification, requiring acknowledgement.
totp
string
Time-based one-time passcode. The user accesses this code through on-hand devices, for example, an authenticator app that displays a new passcode every 60 seconds.
prompt
string
The text prompting users for the passcode. Plaid will relay the user's locale using the Accept-Language header. If the partner doesn't provide this text, Plaid falls back to its own prompt wording.
Copy
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
string
Unique identifier useful for tracing this request, when debugging.
error
requiredobject
Generic error object.
id
string
Opaque identifier, expected to be consistent for errors which have the same cause.
message
string
Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.
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}/sendOtp

Request fields and example

challenge_id
requiredstring
The ID for the escalation flow instance.
send_method_id
requiredstring
The ID for the send method.
Copy
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
string
Unique identifier useful for tracing this request, when debugging.
error
requiredobject
Generic error object.
id
string
Opaque identifier, expected to be consistent for errors which have the same cause.
message
string
Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.
Was this helpful?
503

Signifying the institution is currently unavailable to respond to the request.

error
requiredobject
Generic error object.
retry_at
string
The time, in UTC, when the institution is expected to support aggregation again.

Format: date-time
id
string
Opaque identifier, expected to be consistent for errors which have the same cause.
message
string
Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.
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
requiredstring
The ID for the escalation flow instance.
passcode
requiredstring
The submitted TOTP or OTP passcode.
Copy
1
Was this helpful?
Copy
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'

Validate KBA

ValidateKbaChallengeRequest

Request to validate KBA challenge answers.

challenge_id
requiredstring
The ID for the escalation flow instance.
answers
required[object]
question_id
string
The ID for the challenge question.
text
string
The submitted answer.
Copy
1
Was this helpful?
Copy
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.

users/{user_id}/2fa

Response fields and example

user_id
requiredstring
Opaque user identifier.
auth_token
requiredstring
Opaque, revocable token.
Copy
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
string
Unique identifier useful for tracing this request, when debugging.
error
requiredobject
Generic error object.
id
string
Opaque identifier, expected to be consistent for errors which have the same cause.
message
string
Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.
Was this helpful?
401 Not Authorized

Response indicating the presence of an error.

request_id
string
Unique identifier useful for tracing this request, when debugging.
error
requiredobject
Generic error object.
id
string
Opaque identifier, expected to be consistent for errors which have the same cause.
message
string
Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.
Was this helpful?
503

Signifying the institution is currently unavailable to respond to the request.

error
requiredobject
Generic error object.
retry_at
string
The time, in UTC, when the institution is expected to support aggregation again.

Format: date-time
id
string
Opaque identifier, expected to be consistent for errors which have the same cause.
message
string
Brief description of the error, intended for display purposes. Under certain conditions, Plaid may modify or replace the message e.g. in response to suspicious user activity.
Was this helpful?