Authentication

This section will help you prepare your OAuth 2.0 provider for connecting to Plaid.

If you are using your existing OAuth identity provider. (For example, Okta, Auth0, Ping Identity, Azure Active Directory, AWS Cognito), please prepare all the URLs and settings required for access. This include firewall rules, scopes and audiences. Initially have these URLs ready:

Note: OIDC Discovery (Well Known Config) and JWKS are not supported in Plaid Exchange

In order to allow Plaid to authenticate its request for an access token, you will need to issue a client ID and client secret. You may create the client ID and client secret using your preferred method, but we provide some guidance in this guide. Once you have created a client ID and client secret, provide them to your Plaid contact.

Once you have a server and have issued Plaid a client ID and client secret, the authorization flow occurs as follows:

1. Plaid redirects the end user to your authorization_endpoint.
2. The user completes all authentication steps and you generate an authorization code.
3. Plaid uses the authorization code to request an access token.
4. Plaid uses the access token to identify the user (unique consistency key).

(This described authentication flow conforms to commonly implemented patterns for the OIDC spec. Plaid welcomes partner feedback.)

In order to register an application for your server, you will need to create a client ID and client secret. These will be shared with Plaid so that the Plaid can identify itself. Below, you will find best practices and code samples to help you create a client ID and client secret.

A client ID is a public identifier that you assign to Plaid. While it is not secret, we recommend choosing a client ID that is not easy to guess.

One way to create a client ID is to use a random 32-character hex string. See the code samples below:

1require('crypto').randomBytes(16).toString('hex');

The client secret is essentially a password that you assign to Plaid. In order to keep it secure, please follow these best practices:

• Generate the client secret in a way that makes it impossible to guess or backwards-generate. (For example, do not use a UUID as many common libraries take into account the timestamp or MAC address of the generating server).
• Never store the client secret in plain text—always keep it encrypted or hashed.
• Make the client secret visually different from the client ID. (This reduces the risk of a user copy/paste error when handling the client ID and client secret).

One way to securely generate a client secret is to follow the steps below:

1. Create a 256-bit value using a cryptographically secure pseudo random number generator (CSPRNG).
2. Convert the value from step 1 to a hexadecimal representation.

See the code samples below:

1require('crypto').randomBytes(32).toString('hex');

When your user first initiates the process of linking their account, Plaid redirects their browser to the authorization_endpoint. Plaid's redirect includes these query parameters:

Optional fields can be requested, please contact Plaid to learn more.

Plaid's redirect:

1https://auth.firstplatypus.com/oauth2/v1/authorize?response_type=code&redirect_uri=https%3A%2F%2Fcdn.plaid.com%2Flink%2Fv2%2Fstable%2Foauth.html&scope=openid%20offline_access&client_id=c5a5245b062bf8420d11ab4361b28a15&state=eyJvYXV0aF9zdGF0ZV

This page will be requested directly by the user's device. Your authorization endpoint must support TLS and be publicly accessible. Control of user authentication has now been handed off to you. A typical authentication flow will include a username and password submission form and a 2FA step. For partners with native mobile applications, Plaid strongly recommends enabling support for App2App and using biometric authentication to improve the user's authentication experience.

After the user completes all required authentication steps, your organization generates a temporary authorization code and redirects the user's browser back to the redirect_uri. The following query parameters must be included with the request:

Your response:

1https://cdn.plaid.com/link/v2/stable/oauth.html?code=1284918391&state=eyJvYXV0aF9zdGF0ZV

Plaid sends a request to your token_endpoint. Unlike the two previous steps, the request to token_endpoint is a backend-to-backend call and must be authenticated. The authentication credentials consist of the client ID and client secret you issued to Plaid. The authentication method will be one of the authentication methods specified in your well-known configuration.

For example, if the authentication method is set to client_secret_basic, Plaid will include a basic authentication header in its request.

Plaid will also send the authorization code (code) in the body of the request and expects to receive an access_token, id_token, and refresh_token in your response.

Plaid's request:

1curl --request POST 'https://auth.firstplatypusbank.com/oauth2/v1/token' \
2--header 'Content-Type: application/json' \
3--header "Authorization: Basic YzVhNTI0NWIwNjJiZjg0MjBkMTFhYjQzNjFiMjhhMTU6clZYWU9vUVM0ckhVRzc5bl80OGFs"
4--data-raw '{
5    "grant_type": "authorization_code",
6    "code": "1284918391",
7    "redirect_url": "https://cdn.plaid.com/link/v2/stable/oauth.html"
8}'

Your organization validates that the client_id, client_secret, code and redirect_uri parameters from Plaid's request all match the expected values. Your response to this request contains everything that Plaid needs to later access your Plaid Exchange API:

Your response:

1{
2  "access_token": "agstynmdygjdghabrgraeh...",
3  "id_token": "snsyjrhvjdtvyjvsgcegaethstj...",
4  "user_id": "2347456437346745", // Optional, see above
5  "refresh_token": "dhcsrtjsrgayvkdisfdgntshstu..."
6}

If user_id and id_token are not present, the final attempt to resolve the unique consistency key will be via the FDX endpoint called /customer/current. The response is listed below.

1{
2  "customerId": "2347456437346745"
3}

After it receives this response, Plaid has everything it needs to access your Plaid Exchange API.

For some use cases, Plaid needs to periodically fetch fresh data on behalf of the user. To get a new access token, Plaid makes another request to your token_endpoint with a different set of parameters.

Plaid's request:

1curl --request POST 'https://auth.firstplatypusbank.com/oauth2/v1/token' \
2--user "plaid:rVXYOoQS4rHUG79n_48al"
3--header 'Content-Type: application/json' \
4--data-raw '{
5    "grant_type": "refresh_token",
6    "refresh_token": "dhcsrtjsrgayvkdisfdgntshstu..."
7}'

Your response:

1{
2  "access_token": "lngarogglkcangasgabba...",
3  "expires_in": 900,
4  "id_token": "snsyjrhvjdtvyjvsgcegaethstj..."
5}

See the previous section for descriptions of these response parameters.

How to handle an error that occurs during the authorization flow.

If the request fails due to an incorrect, missing, invalid, or mismatched redirect_uri, notify Plaid of the error and do not redirect the user to the redirect_uri. We recommend displaying an error page to notify the user that an error has occurred.

If the user cancels the request or if the request fails for any other reason other than an incorrect URI, include the following required query parameters with the request. (Please see the OAuth spec for a complete list of possible parameters.)

See the table below for a full list of possible errors, as defined in the OAuth spec.

Your response:

1https://cdn.plaid.com/link/v2/stable/oauth.html?error=access_denied&state=eyJvYXV0aF9zdGF0ZV

OAuth is the preferred security method. However there are many existing integrations using the MFA/OTP options for authenticating a user. Plaid will continue to support these methods, but they are deprecated for new users.

Please work with Plaid if you have a limitation to OAuth and must use OTP or MFA.

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 auth methods.
• 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 auth methods.

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{
2  "passcode": "123456"
3}

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