Plaid logo
Docs
ALL DOCS

Auth

  • Introduction to Auth
  • Add Auth to your app
  • Money movement partnerships
  • Increasing pay-by-bank adoption
  • Additional Auth flows
Plaid logo
Docs
Close search modal
Ask Bill!
Ask Bill!
Hi! I'm Bill! You can ask me all about the Plaid API. Try asking questions like:
    Note: Bill isn't perfect. He's just a robot platypus that reads our docs for fun. You should treat his answers with the same healthy skepticism you might treat any other answer on the internet. This chat may be logged for quality and training purposes. Please don't send Bill any PII -- he's scared of intimacy. All chats with Bill are subject to Plaid's Privacy Policy.
    Plaid.com
    Log in
    Get API Keys
    Open nav

    Add Auth to your app

    Use Auth to connect user bank accounts

    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.

    Prefer to learn by watching? A video guide is available for this topic.

    Get Plaid API keys and complete application and company profile

    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.

    Install and initialize Plaid libraries

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

    Select Language
    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 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.

    Select Language
    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);

    Create an Item using Link

    These instructions cover Link for web applications. For instructions on using Link in mobile apps, see the Link documentation.

    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.

    Create a Link token
    Select Language
    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 the Link token

    If your use case involves a pay-by-bank payments flow where the end user can choose between paying via a credit card and paying via a bank account, it is highly recommended to use the Embedded experience for Link to increase uptake of pay-by-bank. If your use case is an account opening or funding flow that requires the customer to use a bank account, or has a surcharge for credit card use, use the standard Link experience.

    Select group for content switcher
    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});
    22
    23handler.open();

    The sample code below is for JavaScript. For more examples for other platforms, see Embedded Link.

    1<div id="plaid-embedded-link-container"></div>
    1// The container at `#plaid-embedded-link-container` will need to be sized in order to
    2// control the size of the embedded Plaid module
    3const embeddedLinkOpenTarget = document.querySelector('#plaid-embedded-link-container');
    4
    5Plaid.createEmbedded(
    6 {
    7 token: 'GENERATED_LINK_TOKEN',
    8 onSuccess: (public_token, metadata) => {},
    9 onLoad: () => {},
    10 onExit: (err, metadata) => {},
    11 onEvent: (eventName, metadata) => {},
    12 },
    13 embeddedLinkOpenTarget,
    14);

    Obtain an access token

    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.

    Exchange public token for an access token
    Select group for content switcher
    Select Language
    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});

    Getting Auth data

    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.

    Select group for content switcher
    Select Language
    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}

    Moving funds with a payment partner

    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.

    Select group for content switcher
    Select Language
    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}

    Tutorial and 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.

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

    Next steps

    Once Auth is implemented in your app, see Micro-deposit and database verification to make sure your app is supporting the maximum number of institutions and verification methods (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.

    Launch checklist

    Recommended steps to take before launching in Production

    Launch

    Launch checklist

    Recommended steps to take before launching in Production

    Launch
    Was this helpful?
    Developer community
    GitHub
    GitHub
    Stack Overflow
    Stack Overflow
    YouTube
    YouTube
    Discord
    Discord