Plaid logo
Docs
ALL DOCS

Auth

  • Introduction to Auth
  • Add Auth to your app
  • Move money with our partners
  • Add institution coverage
Plaid logo
Docs
Plaid.com
Get API keys
Open nav

Instant Auth & Instant Match

Learn how to authenticate your users instantly

Instant Auth

Instant Auth supports more than 3,800 financial institutions with credential-based login. Instant Auth is the default Auth flow and does not require extra configuration steps if Auth is already configured in your app. For clarity and completeness, the section below explains how to configure Instant Auth.

Instant Auth Link flow

You can try out the Instant Match flow in Link Demo. See more details in our testing guide.

Configure & Create a link_token

Create a link_token with the following parameters:

  • products array containing auth – If you are using only auth and no other products, auth must be specified in the Products array. Other products (such as identity) may be specified as well. If you are using multiple products, auth is not required to be specified in the products array, but including it is recommended for the best user experience.
Select group for content switcher
Select Language
Copy
1app.post('/api/create_link_token', async function (request, response) {
2 // Get the client_user_id by searching for the current user
3 const user = await User.find(...);
4 const clientUserId = user.id;
5 const request = {
6 user: {
7 // This should correspond to a unique id for the current user.
8 client_user_id: clientUserId,
9 },
10 client_name: 'Plaid Test App',
11 products: ['auth'],
12 language: 'en',
13 webhook: 'https://webhook.example.com',
14 redirect_uri: 'https://domainname.com/oauth-page.html',
15 country_codes: ['US'],
16 };
17 try {
18 const createTokenResponse = await client.linkTokenCreate(request);
19 response.json(createTokenResponse.data);
20 } catch (error) {
21 // handle error
22 }
23});
Initialize Link with a link_token

After creating a link_token for the auth product, use it to initialize Plaid Link.

When the user inputs their username and password for the financial institution, the onSuccess() callback function will return a public_token.

Select Language
Copy
1Plaid.create({
2 // Fetch a link_token configured for 'auth' from your app server
3 token: (await $.post('/create_link_token')).link_token,
4 onSuccess: (public_token, metadata) => {
5 // Send the public_token and accounts to your app server
6 $.post('/exchange_public_token', {
7 publicToken: public_token,
8 accounts: metadata.accounts,
9 });
10 },
11});
Exchange the public_token and fetch Auth data

In your own backend server, call the /item/public_token/exchange endpoint with the Link public_token received in the onSuccess callback to obtain an access_token. Persist the returned access_token and item_id in your database in relation to the user. You will use the access_token when making requests to the /auth/get endpoint.

Select group for content switcher
Select Language
Copy
1const publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d';
2
3try {
4 // Obtain an access_token from the Link public_token
5 const tokenResponse = await client.itemPublicTokenExchange({
6 public_token: publicToken}),
7 const accessToken = tokenResponse.access_token;
8
9 // Instantly fetch Auth numbers
10 const request: AuthGetRequest = {
11 access_token: accessToken,
12 };
13 const response = await plaidClient.authGet(request);
14 const numbers = response.numbers;
15} catch (err) {
16 // handle error
17}

Check out the /auth/get API reference documentation to see the full Auth request and response schema.

Copy
1{
2 "numbers": {
3 "ach": [
4 {
5 "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
6 "account": "9900009606",
7 "routing": "011401533",
8 "wire_routing": "021000021"
9 }
10 ],
11 "eft": [],
12 "international": [],
13 "bacs": []
14 },
15 "accounts": [{ Object }],
16 "item": { Object },
17 "request_id": "m8MDnv9okwxFNBV"
18}

Instant Match

Instant Match is available for nearly 3,000 U.S. additional financial institutions where Instant Auth is not available. Instant Match is enabled automatically for Auth customers and is automatically provided at supported institutions as a fallback experience when Instant Auth is not available. When using Instant Match, Plaid Link will prompt your user to enter their account number and routing number for a depository account. Plaid will then verify the last four digits of the user-provided account number against the account mask retrieved from the financial institution.

You can try out the Instant Match flow in Link Demo. See more details in our testing guide.

Configuring in Link

Instant Match will be enabled automatically if you configure the link_token with the following parameters:

  • add "auth" to products array
  • country_codes set to ['US']

Optionally, you can disable Instant Match via the /link/token/create call, by setting "auth.instant_match_enabled": false in the request body or by contacting your Account Manager.

Select Language
Copy
1const request: LinkTokenCreateRequest = {
2 user: { client_user_id: new Date().getTime().toString() },
3 client_name: 'Plaid App',
4 products: [Products.Auth],
5 country_codes: [CountryCode.Us],
6 language: 'en',
7};
8try {
9 const response = await plaidClient.linkTokenCreate(request);
10 const linkToken = response.data.link_token;
11} catch (error) {
12 // handle error
13}
Handling Link events

For a user who goes through the Instant Match flow, the TRANSITION_VIEW (view_name = NUMBERS) event will occur after SUBMIT_CREDENTIALS, and in the onSuccess callback the verification_status will be null because the user would have been verified instantly.

Copy
1OPEN (view_name = CONSENT)
2TRANSITION_VIEW view_name = SELECT_INSTITUTION)
3SEARCH_INSTITUTION
4SELECT_INSTITUTION
5TRANSITION_VIEW (view_name = CREDENTIAL)
6SUBMIT_CREDENTIALS
7TRANSITION_VIEW (view_name = LOADING)
8TRANSITION_VIEW (view_name = MFA, mfa_type = code)
9SUBMIT_MFA (mfa_type = code)
10TRANSITION_VIEW (view_name = LOADING)
11TRANSITION_VIEW (view_name = SELECT_ACCOUNT)
12TRANSITION_VIEW (view_name = NUMBERS)
13TRANSITION_VIEW (view_name = LOADING)
14TRANSITION_VIEW (view_name = CONNECTED)
15HANDOFF
16onSuccess (verification_status: null)

Automated Micro-deposits

Integrate the automated micro-deposit flow

View guide

Same Day Micro-deposits

Integrate the manual micro-deposit flow

View guide

Testing in Sandbox

Learn how to test each Auth flow in the Sandbox

View guide
Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Twitter
Twitter
Discord
Discord