Add Auth to your app

In this guide, we'll demonstrate how to add Auth to your app so that you can connect to your users' bank accounts and obtain the information needed to set up funds transfers.

If you're already familiar with using Plaid and are set up to make calls to the Plaid API, see Getting Auth data. If you're interested in using a Plaid partner, such as Stripe or Dwolla, to process payments, see Moving funds with a payment partner.

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 Dashboard.

You will also need to complete your application profile and company profile in the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal. Your application profile and company profile must be completed before connecting to certain institutions in Production.

You can use our official server-side client libraries to connect to the Plaid API from your application:

1// Install via npm
2npm install --save plaid

After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox, Development, or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include them in any other calls.

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. These code samples also demonstrate starting up a server commonly used in each framework (such as Express or Flask).

1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16});
17
18const client = new PlaidApi(configuration);

Plaid Link is the client-side component that your users interact with to securely connect their bank accounts to your app. An Item is created when a user successfully logs into their financial institution using Link. An Item represents a single login at a financial institution. Items do not represent individual bank accounts, although all bank accounts are associated with an Item. For example, if a user has a single login at a bank that allows them to access both a checking account and a savings account, only a single Item would be associated with both of the accounts.

When using Auth, you will typically only need access to the specific bank account that will be used to transfer funds, rather than all of the accounts a user may have at an institution. Because of this, it is recommended that you configure Link with Account Select when using Auth. Configuring Link with Account Select will limit unnecessary access to user accounts. You can enable Account Select from the Dashboard.

To create an Item, you'll first need to create a Link token on your application server. You can create a Link token by calling the /link/token/create endpoint. Then, on the client-side of your application, you'll initialize Link with using the Link token you created.

The code samples below demonstrate how to create a Link token and how to initialize Link using the token.

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});

1const handler = Plaid.create({
2  token: (await $.post('/create_link_token')).link_token,
3  onSuccess: (public_token, metadata) => {
4    // Upon successful linking of a bank account,
5    // Link will return a public token.
6    // Exchange the public token for an access token
7    // to make calls to the Plaid API.
8    $.post('/exchange_public_token', {
9      public_token: public_token,
10    });
11  },
12  onLoad: () => {},
13  onExit: (err, metadata) => {
14    // Optionally capture when your user exited the Link flow.
15    // Storing this information can be helpful for support.
16  },
17  onEvent: (eventName, metadata) => {
18    // Optionally capture Link flow events, streamed through
19    // this callback as your users connect an Item to Plaid.
20  },
21  //required for OAuth;
22  receivedRedirectUri: window.location.href,
23});
24
25handler.open();

When a user successfully links an Item via Link, the onSuccess callback will be called. The onSuccess callback returns a public token. On your application server, exchange the public token for an access token and an Item ID by calling /item/public_token/exchange/. The access token will allow you to make authenticated calls to the Plaid API.

Store 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 expire it via rotation or remove it by calling /item/remove on the corresponding Item. For security purposes, never store the access token in client-side code. The public token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

1app.post('/api/exchange_public_token', async function (
2  request,
3  response,
4  next,
5) {
6  const publicToken = request.body.public_token;
7  try {
8    const response = await client.itemPublicTokenExchange({
9      public_token: publicToken,
10    });
11
12    // These values should be saved to a persistent database and
13    // associated with the currently signed-in user
14    const accessToken = response.data.access_token;
15    const itemID = response.data.item_id;
16
17    res.json({ public_token_exchange: 'complete' });
18  } catch (error) {
19    // handle error
20  }
21});

Now that you have an access token, you can begin making authenticated calls to the Plaid API. If you are processing payments yourself, the /auth/get endpoint to retrieve the bank account and bank identification numbers (such as routing numbers, for US accounts) associated with an Item's accounts. You can then supply these to your payment system. If you are using a Plaid partner to move funds, you will not need to call /auth/get. Instead, see Moving funds with a payment partner.

Note that if your Plaid integration uses automated or same-day micro-deposits, you'll need to wait one to two business days before you are able to make calls to the Auth API. For more information, see Add institution coverage.

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

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

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

You can move money via ACH transfer by pairing Auth with one of Plaid's payment partners. When using a partner to move money, the partner's payments service will initiate the transfer; Plaid does not function as the payment processor. For the full list of payments platforms who have partnered with Plaid to provide ACH money movement, see Auth Partnerships.

To move money using a Plaid partner, first create an Item using Link and obtain an access token as described above. Then, instead of calling Plaid's Auth endpoints, call one of Plaid's processor token endpoints to create a processor token. You can then send this processor token to one of Plaid's partners by using endpoints that are specific to the payment platform. Refer to the partner's technical documentation for more information. Using a partner to transfer funds gives you access to payment functionality while freeing you from having to securely store sensitive bank account information.

The sample code below demonstrates a call to /processor/token/create using Dwolla as the payment processor.

1const { ProcessorTokenCreateRequest } = require('plaid');
2
3try {
4  // Create a processor token for a specific account id
5  const request: ProcessorTokenCreateRequest = {
6    access_token: accessToken,
7    account_id: accountID,
8    processor: 'dwolla',
9  };
10  const processorTokenResponse = await plaidClient.processorTokenCreate(
11    request,
12  );
13  const processorToken = processorTokenResponse.processor_token;
14} catch (error) {
15  // handle error
16}

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.

For a step-by-step tutorial on how to implement account funding, Account funding tutorial.

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).

If your use case is an account funding use case, see the Account funding solutions guide for a set of recommendations on how to implement Auth.

If you're ready to launch to Production, see the Launch checklist.