Add Auth to your app

Use Auth to connect user bank accounts

In this guide, we'll start from scratch and walk through how to use Auth to connect to your users' bank accounts and obtain the information needed to set up funds transfers. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to Fetching auth data.

Note that these instructions are intended for using Auth without a Plaid partner. If you will be using a Plaid partner such as Stripe or Dwolla to process payments, see Auth payment partners to find the specific instructions for your payment processor.

Get Plaid API keys

If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid developer dashboard.

Install Plaid libraries

You can use our official libraries to connect to the Plaid API from your application:

Terminal
1
2
# Install via npm
npm install --save plaid

Create an Item in Link

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation.

Using Link, we will create a Plaid Item, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the Dashboard.

Before initializing Link, you will need to create a new link_token on the server side of your application. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, you'll need to initialize Link with the link_token that you just created.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard.

Create a link_token

server.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
// Using Express
const express = require('express');
const app = express();
app.use(express.json());
const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
const configuration = new Configuration({
  basePath: PlaidEnvironments[process.env.PLAID_ENV],
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});
const client = new PlaidApi(configuration);
app.post('/api/create_link_token', async function (request, response) {
  // Get the client_user_id by searching for the current user
  const user = await User.find(...);
  const clientUserId = user.id;
  const request = {
    user: {
      // This should correspond to a unique id for the current user.
      client_user_id: clientUserId,
    },
    client_name: 'Plaid Test App',
    products: [Products.Auth],
    language: 'en',
    webhook: 'https://webhook.example.com',
    country_codes: [CountryCode.Us],
  };
  try {
    const createTokenResponse = await client.linkTokenCreate(request);
    response.json(createTokenResponse.data);
  } catch (error) {
    // handle error
  }
});

Install Link dependency

index.html
1
2
3
4
<head>
  <title>Connect a bank</title>
  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
</head>

Configure the client-side Link handler

app.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
const linkHandler = Plaid.create({
  token: (await $.post('/create_link_token')).link_token,
  onSuccess: (public_token, metadata) => {
    // Send the public_token to your app server.
    $.post('/exchange_public_token', {
      public_token: public_token,
    });
  },
  onExit: (err, metadata) => {
    // Optionally capture when your user exited the Link flow.
    // Storing this information can be helpful for support.
  },
  onEvent: (eventName, metadata) => {
    // Optionally capture Link flow events, streamed through
    // this callback as your users connect an Item to Plaid.
  },
});
linkHandler.open();

Get a persistent access_token

Next, on the server side, we need to exchange our public_token for an access_token and item_id. The access_token will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the /item/public_token/exchange endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the access_token and item_id in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The access_token will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via /item/remove. The access_token should be stored securely, and never in client-side code. A public_token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

server.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// Using Express
const express = require('express');
const app = express();
app.use(express.json());
const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
const configuration = new Configuration({
  basePath: PlaidEnvironments[process.env.PLAID_ENV],
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
      'Plaid-Version': '2020-09-14',
    },
  },
});
const client = new PlaidApi(configuration);
app.post(
  '/api/exchange_public_token',
  async function (request, response, next) {
    const publicToken = request.body.public_token;
    try {
      const response = await client.itemPublicTokenExchange({
        public_token: publicToken,
      });
      const accessToken = response.data.access_token;
      const itemID = response.data.item_id;
    } catch (error) {
      // handle error
    }
  },
);

Fetching Auth data

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. Once you've retrieved the numbers for an account, you can supply them to your payments system to set up funds transfers. For more detailed information on the schema for account information returned by /auth/get, see the Auth Reference.

server.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// Use Auth and pull account numbers for an Item
const request: AuthGetRequest = {
  access_token: testAccessToken as string,
};
try {
  const response = await plaidClient.authGet(request);
  const accountData = response.data.accounts;
  if (response.data.numbers.ach.length > 0) {
    // Handle ACH numbers (US accounts)
    const achNumbers = response.data.numbers.ach;
  }
  if (response.data.numbers.eft.length > 0) {
    // Handle EFT numbers (Canadian accounts)
    const eftNumbers = response.data.numbers.eft;
  }
  if (response.data.numbers.international.length > 0) {
    // Handle International numbers
    const internationalNumbers = response.data.numbers.international;
  }
  if (response.data.numbers.bacs.length > 0) {
    // Handle BACS numbers (British accounts)
    const bacsNumbers = response.data.numbers.bacs;
  }
} catch (error) {
  //handle error
}

Example response data is below. Note that this is test account data; real accounts would not have all four sets of numbers.

Auth sample response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
{
  "accounts": [
    {
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "balances": {
        "available": 100,
        "current": 110,
        "limit": null,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "mask": "9606",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Checking",
      "subtype": "checking",
      "type": "depository"
    }
  ],
  "numbers": {
    "ach": [
      {
        "account": "9900009606",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "routing": "011401533",
        "wire_routing": "021000021"
      }
    ],
    "eft": [
      {
        "account": "111122223333",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "institution": "021",
        "branch": "01140"
      }
    ],
    "international": [
      {
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "bic": "NWBKGB21",
        "iban": "GB29NWBK60161331926819"
      }
    ],
    "bacs": [
      {
        "account": "31926819",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "sort_code": "601613"
      }
    ]
  },
  "item": {
    "available_products": [
      "balance",
      "identity",
      "payment_initiation",
      "transactions"
    ],
    "billed_products": ["assets", "auth"],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_117650",
    "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "request_id": "m8MDnv9okwxFNBV"
}

Example code in Plaid Pattern

For a real-life example of an app that incorporates Auth, see the Node-based Plaid Pattern Account Funding sample app. Pattern Account Funding is a sample account funding app that fetches Auth data in order to set up funds transfers. The Auth code can be found in items.js

Next steps

Once Auth is implemented in your app, see Full Auth coverage to make sure your app is supporting the maximum number of institutions (US only).