Plaid logo
Docs
ALL DOCS

API

  • Overview
  • Libraries
  • API versioning
  • Postman Collection
  • Webhooks
Product API reference
  • Transactions
  • Auth
  • Balance
  • Identity
  • Assets
  • Investments
  • Liabilities
  • Payment Initiation
  • Virtual Accounts
  • Transfer (beta)
  • Income
  • Identity Verification
  • Monitor
  • Signal
  • Enrich
Other API reference
  • Item endpoints and webhooks
  • Account endpoints and schemas
  • Institution endpoints
  • Token flow and endpoints
  • Processor endpoints
  • Sandbox endpoints
  • Reseller partner endpoints
Plaid logo
Docs
Plaid.com
Get API keys
Open nav

Token endpoints

API reference for obtaining and managing tokens from Link

Token exchange flow

Most API calls to Plaid endpoints require an access_token. An access_token provides access to a specific Item, which is a Plaid term for a login at a financial institution.

The primary flow for obtaining a Plaid access_token works as follows:

  1. Obtain a link_token by calling /link/token/create.
  2. Initialize Link by passing in the link_token. When your user completes the Link flow, Link will pass back a public_token via the onSuccess callback. For more information on initializing and receiving data back from Link, see the Link documentation.
  3. Exchange the public_token for an access_token by calling /item/public_token/exchange.

The access_token can then be used to call Plaid endpoints and obtain information about an Item.

In addition to the primary flow, several other token flows exist. The Link update mode flow allows you to update an access_token that has stopped working. The Sandbox testing environment also offers the /sandbox/public_token/create endpoint, which allows you to create a public_token without using Link.

Token endpoints

In this section
/link/token/createCreate a token for initializing a Link session
/link/token/getGet details about a previously created Link token
/item/public_token/exchangeExchange a public token from Link for an access token
/item/access_token/invalidateRotate an access token without deleting the Item
/item/public_token/create(Deprecated) Create a public token for legacy flows

/link/token/create

Create Link Token

The /link/token/create endpoint creates a link_token, which is required as a parameter when initializing Link. Once Link has been initialized, it returns a public_token, which can then be exchanged for an access_token via /item/public_token/exchange as part of the main Link flow.
A link_token generated by /link/token/create is also used to initialize other Link flows, such as the update mode flow for tokens with expired credentials, or the Payment Initiation (Europe) flow.

link/token/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_name
requiredstring
The name of your application, as it should be displayed in Link. Maximum length of 30 characters. If a value longer than 30 characters is provided, Link will display "This Application" instead.
language
requiredstring
The language that Link should be displayed in. When initializing with Identity Verification, this field is not used; for more details, see Identity Verification supported languages.
Supported languages are:
  • Danish ('da')
  • Dutch ('nl')
  • English ('en')
  • Estonian ('et')
  • French ('fr')
  • German ('de')
  • Italian ('it')
  • Latvian ('lv')
  • Lithuanian ('lt')
  • Norwegian ('no')
  • Polish ('pl')
  • Portuguese ('pt')
  • Romanian ('ro')
  • Spanish ('es')
  • Swedish ('se')

When using a Link customization, the language configured here must match the setting in the customization, or the customization will not be applied.
country_codes
required[string]
Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Institutions from all listed countries will be shown. For a complete mapping of supported products by country, see https://plaid.com/global/.
If Link is launched with multiple country codes, only products that you are enabled for in all countries will be used by Link. Note that while all countries are enabled by default in Sandbox and Development, in Production only US and Canada are enabled by default. Access to European institutions requires additional compliance steps. To request access to European institutions in the Production environment, file a product access Support ticket via the Plaid dashboard. If you initialize with a European country code, your users will see the European consent panel during the Link flow.
If using a Link customization, make sure the country codes in the customization match those specified in country_codes, or the customization may not be applied.
If using the Auth features Instant Match, Same-day Micro-deposits, or Automated Micro-deposits, country_codes must be set to ['US'].


Min items: 1
Possible values: US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT
user
requiredobject
An object specifying information about the end user who will be linking their account.
client_user_id
requiredstring
A unique ID representing the end user. Typically this will be a user ID number from your application. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id. It is currently used as a means of searching logs for the given user in the Plaid Dashboard.
legal_name
string
The user's full legal name, used for micro-deposit based verification flows. For a small number of customers on legacy flows, providing this field is required to enable micro-deposit-based flows. For all other customers, this field is optional, but providing the user's name in this field when using micro-deposit-based verification will enable certain risk checks and can reduce micro-deposit fraud.
name
object
The user's full name. Optional if using the Identity Verification product; if not using Identity Verification, this field is not allowed. Users will not be asked for their name when this field is provided.
given_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
phone_number
string
The user's phone number in E.164 format. This field is optional, but required to enable the returning user experience.
phone_number_verified_time
deprecatedstring
The date and time the phone number was verified in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ). This was previously an optional field used in the returning user experience. This field is no longer required to enable the returning user experience.
Only pass a verification time for a phone number that you have verified. If you have performed verification but don’t have the time, you may supply a signal value of the start of the UNIX epoch.
Example: 2020-01-01T00:00:00Z


Format: date-time
email_address
string
The user's email address. This field is optional, but required to enable the pre-authenticated returning user flow.
email_address_verified_time
deprecatedstring
The date and time the email address was verified in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ). This was previously an optional field used in the returning user experience. This field is no longer required to enable the returning user experience.
Only pass a verification time for an email address that you have verified. If you have performed verification but don’t have the time, you may supply a signal value of the start of the UNIX epoch.
Example: 2020-01-01T00:00:00Z


Format: date-time
ssn
deprecatedstring
To be provided in the format "ddd-dd-dddd". Not currently used.
date_of_birth
deprecatedstring
To be provided in the format "yyyy-mm-dd". Not currently used.

Format: date
address
object
Home address for the user.
street
requiredstring
The primary street portion of an address. If the user has submitted their address, this field will always be filled.
street2
string
Extra street information, like an apartment or suite number.
city
requiredstring
City from the end user's address
region
requiredstring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
requiredstring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
requiredstring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
id_number
object
ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.
value
requiredstring
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
requiredstring
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
products
[string]
List of Plaid product(s) you wish to use. If launching Link in update mode, should be omitted; required otherwise.
balance is not a valid value, the Balance product does not require explicit initialization and will automatically be initialized when any other product is initialized.
The products specified here will determine which institutions will be available to your users in Link. Only institutions that support all requested products can be selected; a if a user attempts to select an institution that does not support a listed product, a "Connectivity not supported" error message will appear in Link. To maximize the number of institutions available, initialize Link with the minimal product set required for your use case. Additional products can be added after Link initialization by calling the relevant endpoints. For details and exceptions, see Choosing when to initialize products.
Note that, unless you have opted to disable Instant Match support, institutions that support Instant Match will also be shown in Link if auth is specified as a product, even though these institutions do not contain auth in their product array.
In Production, you will be billed for each product that you specify when initializing Link. Note that a product cannot be removed from an Item once the Item has been initialized with that product. To stop billing on an Item for subscription-based products, such as Liabilities, Investments, and Transactions, remove the Item via /item/remove.


Possible values: assets, auth, employment, identity, income_verification, identity_verification, investments, liabilities, payment_initiation, standing_orders, transactions, transfer, signal
additional_consented_products
[string]
(Beta) This field has no effect unless you are participating in the Product Scope Transparency beta program. List of additional Plaid product(s) you wish to collect consent for. These products will not be billed until you start using them by calling the relevant endpoints.
balance is not a valid value, the Balance product does not require explicit initialization and will automatically have consent collected.
Institutions that do not support these products will still be shown in Link


Possible values: auth, identity, investments, liabilities, transactions, signal
webhook
string
The destination URL to which any webhooks should be sent. Note that webhooks for Payment Initiation, Transfer, Bank Transfer (including Auth micro-deposit notification webhooks) and Identity Verification are configured via the Dashboard instead.
access_token
string
The access_token associated with the Item to update or reference, used when updating, modifying, or accessing an existing access_token. Used when launching Link in update mode, when completing the Same-day (manual) Micro-deposit flow, or (optionally) when initializing Link for a returning user as part of the Transfer UI flow.
link_customization_name
string
The name of the Link customization from the Plaid Dashboard to be applied to Link. If not specified, the default customization will be used. When using a Link customization, the language in the customization must match the language selected via the language parameter, and the countries in the customization should match the country codes selected via country_codes.
redirect_uri
string
A URI indicating the destination where a user should be forwarded after completing the Link flow; used to support OAuth authentication flows when launching Link in the browser or via a webview. The redirect_uri should not contain any query parameters. When used in Production or Development, must be an https URI. To specify any subdomain, use * as a wildcard character, e.g. https://*.example.com/oauth.html. If android_package_name is specified, this field should be left blank. Note that any redirect URI must also be added to the Allowed redirect URIs list in the developer dashboard.
android_package_name
string
The name of your app's Android package. Required if using the link_token to initialize Link on Android. When creating a link_token for initializing Link on other platforms, this field must be left blank. Any package name specified here must also be added to the Allowed Android package names setting on the developer dashboard.
institution_data
object
A map containing data used to highlight institutions in Link.
routing_number
string
The routing number of the bank to highlight.
account_filters
object
By default, Link will provide limited account filtering: it will only display Institutions that are compatible with all products supplied in the products parameter of /link/token/create, and, if auth is specified in the products array, will also filter out accounts other than checking and savings accounts on the Account Select pane. You can further limit the accounts shown in Link by using account_filters to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. This filtering applies to both the Account Select view (if enabled) and the Institution Select view. Institutions that do not support the selected subtypes will be omitted from Link. To indicate that all subtypes should be shown, use the value "all". If the account_filters filter is used, any account type for which a filter is not specified will be entirely omitted from Link. For a full list of valid types and subtypes, see the Account schema.
For institutions using OAuth, the filter will not affect the list of accounts shown by the bank in the OAuth window.
depository
object
A filter to apply to depository-type accounts
account_subtypes
required[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: checking, savings, hsa, cd, money market, paypal, prepaid, cash management, ebt, all
credit
object
A filter to apply to credit-type accounts
account_subtypes
required[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: credit card, paypal, all
loan
object
A filter to apply to loan-type accounts
account_subtypes
required[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: auto, business, commercial, construction, consumer, home equity, loan, mortgage, line of credit, student, other, all
investment
object
A filter to apply to investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier).
account_subtypes
required[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: 529, 401a, 401k, 403B, 457b, brokerage, cash isa, crypto exchange, education savings account, fixed annuity, gic, health reimbursement arrangement, hsa, ira, isa, keogh, lif, life insurance, lira, lrif, lrsp, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other annuity, other insurance, pension, prif, profit sharing plan, qshr, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, sep ira, simple ira, sipp, stock plan, tfsa, trust, ugma, utma, variable annuity, all
eu_config
object
Configuration parameters for EU flows
headless
boolean
If true, open Link without an initial UI. Defaults to false.
institution_id
string
Used for certain Europe-only configurations, as well as certain legacy use cases in other regions.
payment_initiation
object
Specifies options for initializing Link for use with the Payment Initiation (Europe) product. This field is required if payment_initiation is included in the products array. Either payment_id or consent_id must be provided.
payment_id
string
The payment_id provided by the /payment_initiation/payment/create endpoint.
consent_id
string
The consent_id provided by the /payment_initiation/consent/create endpoint.
income_verification
object
Specifies options for initializing Link for use with the Income product. This field is required if income_verification is included in the products array.
income_verification_id
deprecatedstring
The income_verification_id of the verification instance, as provided by /income/verification/create.
asset_report_id
string
The asset_report_id of an asset report associated with the user, as provided by /asset_report/create. Providing an asset_report_id is optional and can be used to verify the user through a streamlined flow. If provided, the bank linking flow will be skipped.
precheck_id
string
The ID of a precheck created with /income/verification/precheck. Will be used to improve conversion of the income verification flow by streamlining the Link interface presented to the end user.
access_tokens
[string]
An array of access tokens corresponding to Items that a user has previously connected with. Data from these institutions will be cross-referenced with document data received during the Document Income flow to help verify that the uploaded documents are accurate. If the transactions product was not initialized for these Items during link, it will be initialized after this Link session.
This field should only be used with the payroll income source type.
income_source_types
[string]
The types of source income data that users will be permitted to share. Options include bank and payroll. Currently you can only specify one of these options.

Possible values: bank, payroll
bank_income
object
Specifies options for initializing Link for use with Bank Income. This field is required if income_verification is included in the products array and bank is specified in income_source_types.
days_requested
requiredinteger
The number of days of data to request for the Bank Income product
enable_multiple_items
boolean
Whether to enable multiple Items to be added in the Link session

Default: false
payroll_income
object
Specifies options for initializing Link for use with Payroll Income.
flow_types
[string]
The types of payroll income verification to enable for the Link session. If none are specified, then users will see both document and digital payroll income.

Possible values: payroll_digital_income, payroll_document_income
is_update_mode
boolean
An identifier to indicate whether the income verification Link token will be used for an update or not

Default: false
item_id_to_update
string
Uniquely identify a payroll income item to update with. It should only be used for update mode.
stated_income_sources
[object]
A list of user stated income sources
employer
string
The employer corresponding to an income source specified by the user
category
string
The income category for a specified income source

Possible values: OTHER, SALARY, UNEMPLOYMENT, CASH, GIG_ECONOMY, RENTAL, CHILD_SUPPORT, MILITARY, RETIREMENT, LONG_TERM_DISABILITY, BANK_INTEREST
pay_per_cycle
number
The income amount paid per cycle for a specified income source

Format: double
pay_annual
number
The income amount paid annually for a specified income source

Format: double
pay_type
string
The pay type - GROSS, NET, or UNKNOWN for a specified income source

Possible values: UNKNOWN, GROSS, NET
pay_frequency
string
The pay frequency of a specified income source

Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY
auth
object
Specifies options for initializing Link for use with the Auth product. This field can be used to enable or disable extended Auth flows for the resulting Link session. Omitting any field will result in a default that can be configured by your account manager.
auth_type_select_enabled
boolean
Specifies whether Auth Type Select is enabled for the Link session, allowing the end user to choose between linking instantly or manually prior to selecting their financial institution. Note that this can only be true if same_day_microdeposits_enabled is set to true.

Default: false
automated_microdeposits_enabled
boolean
Specifies whether the Link session is enabled for the Automated Micro-deposits flow.
instant_match_enabled
boolean
Specifies whether the Link session is enabled for the Instant Match flow. As of November 2022, Instant Match will be enabled by default. Instant Match can be disabled by setting this field to false.
same_day_microdeposits_enabled
boolean
Specifies whether the Link session is enabled for the Same Day Micro-deposits flow.
flow_type
deprecatedstring
This field has been deprecated in favor of auth_type_select_enabled.

Possible values: FLEXIBLE_AUTH
transfer
object
Specifies options for initializing Link for use with the Transfer product.
intent_id
string
The id returned by the /transfer/intent/create endpoint.
payment_profile_token
string
The payment_profile_token returned by the /payment_profile/create endpoint.
update
object
Specifies options for initializing Link for update mode.
account_selection_enabled
boolean
If true, enables update mode with Account Select.

Default: false
identity_verification
object
Specifies option for initializing Link for use with the Identity Verification product.
template_id
requiredstring
ID of the associated Identity Verification template.
gave_consent
boolean
A flag specifying whether the end user has already agreed to a privacy policy specifying that their data will be shared with Plaid for verification purposes.
If gave_consent is set to true, the accept_tos step will be marked as skipped and the end user's session will start at the next step requirement.


Default: false
user_token
string
A user token generated using /user/create. Any Item created during the Link session will be associated with the user.
investments
object
Configuration parameters for the Investments product
allow_unverified_crypto_wallets
boolean
If true, allow self-custody crypto wallets to be added without requiring signature verification. Defaults to false.
Select group for content switcher
Select Language
Copy
1const request: LinkTokenCreateRequest = {
2 user: {
3 client_user_id: 'user-id',
4 },
5 client_name: 'Plaid Test App',
6 products: ['auth', 'transactions'],
7 country_codes: ['US'],
8 language: 'en',
9 webhook: 'https://sample-web-hook.com',
10 redirect_uri: 'https://domainname.com/oauth-page.html',
11 account_filters: {
12 depository: {
13 account_subtypes: ["checking", "savings"],
14 },
15 },
16};
17try {
18 const response = await plaidClient.linkTokenCreate(request);
19 const linkToken = response.data.link_token;
20} catch (error) {
21 // handle error
22}
link/token/create

Response fields and example

link_token
string
A link_token, which can be supplied to Link in order to initialize it and receive a public_token, which can be exchanged for an access_token.
expiration
string
The expiration date for the link_token, in ISO 8601 format. A link_token created to generate a public_token that will be exchanged for a new access_token expires after 4 hours. A link_token created for an existing Item (such as when updating an existing access_token by launching Link in update mode) expires after 30 minutes.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",
3 "expiration": "2020-03-27T12:56:34Z",
4 "request_id": "XQVgFigpGHXkb0b"
5}
Was this helpful?

/link/token/get

Get Link Token

The /link/token/get endpoint gets information about a previously-created link_token using the /link/token/create endpoint. It can be useful for debugging purposes.

link/token/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
link_token
requiredstring
A link_token from a previous invocation of /link/token/create
Select group for content switcher
Select Language
Copy
1const request: LinkTokenGetRequest = {
2 link_token: linkToken,
3};
4try {
5 const response = await plaidClient.linkTokenGet(request);
6} catch (error) {
7 // handle error
8}
link/token/get

Response fields and example

link_token
string
A link_token, which can be supplied to Link in order to initialize it and receive a public_token, which can be exchanged for an access_token.
created_at
nullablestring
The creation timestamp for the link_token, in ISO 8601 format.

Format: date-time
expiration
nullablestring
The expiration timestamp for the link_token, in ISO 8601 format.

Format: date-time
metadata
object
An object specifying the arguments originally provided to the /link/token/create call.
initial_products
[string]
The products specified in the /link/token/create call.

Possible values: assets, auth, employment, identity, income_verification, identity_verification, investments, liabilities, payment_initiation, standing_orders, transactions, transfer
webhook
nullablestring
The webhook specified in the /link/token/create call.
country_codes
[string]
The country_codes specified in the /link/token/create call.

Possible values: US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT
language
nullablestring
The language specified in the /link/token/create call.
institution_data
object
A map containing data used to highlight institutions in Link.
routing_number
string
The routing number of the bank to highlight.
account_filters
object
The account_filters specified in the original call to /link/token/create.
depository
object
A filter to apply to depository-type accounts
account_subtypes
[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: checking, savings, hsa, cd, money market, paypal, prepaid, cash management, ebt, all
credit
object
A filter to apply to credit-type accounts
account_subtypes
[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: credit card, paypal, all
loan
object
A filter to apply to loan-type accounts
account_subtypes
[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: auto, business, commercial, construction, consumer, home equity, loan, mortgage, line of credit, student, other, all
investment
object
A filter to apply to investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier).
account_subtypes
[string]
An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the Account schema.

Possible values: 529, 401a, 401k, 403B, 457b, brokerage, cash isa, crypto exchange, education savings account, fixed annuity, gic, health reimbursement arrangement, hsa, ira, isa, keogh, lif, life insurance, lira, lrif, lrsp, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other annuity, other insurance, pension, prif, profit sharing plan, qshr, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, sep ira, simple ira, sipp, stock plan, tfsa, trust, ugma, utma, variable annuity, all
redirect_uri
nullablestring
The redirect_uri specified in the /link/token/create call.
client_name
nullablestring
The client_name specified in the /link/token/create call.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "created_at": "2020-12-02T21:14:54Z",
3 "expiration": "2020-12-03T01:14:54Z",
4 "link_token": "link-sandbox-33792986-2b9c-4b80-b1f2-518caaac6183",
5 "metadata": {
6 "account_filters": {
7 "depository": {
8 "account_subtypes": [
9 "checking",
10 "savings"
11 ]
12 }
13 },
14 "client_name": "Insert Client name here",
15 "country_codes": [
16 "US"
17 ],
18 "initial_products": [
19 "auth"
20 ],
21 "language": "en",
22 "redirect_uri": null,
23 "webhook": "https://www.example.com/webhook"
24 },
25 "request_id": "u0ydFs493XjyTYn"
26}
Was this helpful?

/item/public_token/exchange

Exchange public token for an access token

Exchange a Link public_token for an API access_token. Link hands off the public_token client-side via the onSuccess callback once a user has successfully created an Item. The public_token is ephemeral and expires after 30 minutes. An access_token does not expire, but can be revoked by calling /item/remove.
The response also includes an item_id that should be stored with the access_token. The item_id is used to identify an Item in a webhook. The item_id can also be retrieved by making an /item/get request.

item/public_token/exchange

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
public_token
requiredstring
Your public_token, obtained from the Link onSuccess callback or /sandbox/item/public_token/create.
Select group for content switcher
Select Language
Copy
1const request: ItemPublicTokenExchangeRequest = {
2 public_token: publicToken,
3};
4try {
5 const response = await plaidClient.itemPublicTokenExchange(request);
6 const accessToken = response.data.access_token;
7 const itemId = response.data.item_id;
8} catch (err) {
9 // handle error
10}
item/public_token/exchange

Response fields and example

access_token
string
The access token associated with the Item data is being requested for.
item_id
string
The item_id value of the Item associated with the returned access_token
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
3 "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
4 "request_id": "Aim3b"
5}
Was this helpful?

/item/access_token/invalidate

Invalidate access_token

By default, the access_token associated with an Item does not expire and should be stored in a persistent, secure manner.
You can use the /item/access_token/invalidate endpoint to rotate the access_token associated with an Item. The endpoint returns a new access_token and immediately invalidates the previous access_token.

item/access_token/invalidate

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
Select group for content switcher
Select Language
Copy
1// Generate a new access_token for an Item, invalidating the old one
2const request: ItemAccessTokenInvalidateRequest = {
3 access_token: accessToken,
4};
5try {
6 const response = await plaidClient.itemAccessTokenInvalidate(request);
7 // Store the new access_token in a persistent, secure datastore
8 const accessToken = response.data.new_access_token;
9} catch (error) {
10 // handle error
11}
item/access_token/invalidate

Response fields and example

new_access_token
string
The access token associated with the Item data is being requested for.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "new_access_token": "access-sandbox-8ab976e6-64bc-4b38-98f7-731e7a349970",
3 "request_id": "m8MDnv9okwxFNBV"
4}
Was this helpful?

/item/public_token/create

Create public token

Note: As of July 2020, the /item/public_token/create endpoint is deprecated. Instead, use /link/token/create with an access_token to create a Link token for use with update mode.
If you need your user to take action to restore or resolve an error associated with an Item, generate a public token with the /item/public_token/create endpoint and then initialize Link with that public_token.
A public_token is one-time use and expires after 30 minutes. You use a public_token to initialize Link in update mode for a particular Item. You can generate a public_token for an Item even if you did not use Link to create the Item originally.
The /item/public_token/create endpoint is not used to create your initial public_token. If you have not already received an access_token for a specific Item, use Link to obtain your public_token instead. See the Quickstart for more information.

item/public_token/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_token
requiredstring
The access token associated with the Item data is being requested for.
Select group for content switcher
Select Language
Copy
1// This endpoint is deprecated and not
2// supported in the Beta libraries
item/public_token/create

Response fields and example

public_token
string
A public_token for the particular Item corresponding to the specified access_token
expiration
string
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
3 "request_id": "Aim3b"
4}
Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Twitter
Twitter
Discord
Discord