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:
- Obtain a
link_token
by calling/link/token/create
. - Initialize Link by passing in the
link_token
. When your user completes the Link flow, Link will pass back apublic_token
via theonSuccess
callback. For more information on initializing and receiving data back from Link, see the Link documentation. - Exchange the
public_token
for anaccess_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/create | Create a token for initializing a Link session |
/link/token/get | Get details about a previously created Link token |
/item/public_token/exchange | Exchange a public token from Link for an access token |
/item/access_token/invalidate | Rotate 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.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.client_name
language
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 (
'sv'
)
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
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']
.1
US
, GB
, ES
, NL
, FR
, IE
, CA
, DE
, IT
, PL
, DK
, NO
, SE
, EE
, LT
, LV
, PT
user
client_user_id
client_user_id
. It is currently used as a means of searching logs for the given user in the Plaid Dashboard.legal_name
name
given_name
family_name
phone_number
phone_number_verified _time
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
date-time
email_address
email_address _verified_time
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
date-time
ssn
id_number
field instead.date_of_birth
date
address
street
street2
city
region
postal_code
country
2
id_number
value
type
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
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 included via the
required_if_supported_products
field, or can be initialized by calling the endpoint after obtaining an access token. 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
.assets
, auth
, employment
, identity
, income_verification
, identity_verification
, investments
, liabilities
, payment_initiation
, standing_orders
, transactions
, transfer
, signal
required_if_supported _products
There should be no overlap between this array and the
products
or additional_consented_products
arrays. The products
array must have at least one product.For more details on using this feature, see Required if Supported Products.
auth
, identity
, investments
, liabilities
, transactions
, statements
optional_products
There should be no overlap between this array and the
products
, required_if_supported_products
, or additional_consented_products
arrays. The products
array must have at least one product.For more details on using this feature, see Optional Products.
auth
, identity
, investments
, liabilities
, statements
, transactions
additional_consented _products
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.
There should be no overlap between this array and the
products
or required_if_supported_products
arrays.assets
, auth
, identity
, investments
, liabilities
, transactions
, signal
webhook
access_token
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
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
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
. Note that any redirect URI must also be added to the Allowed redirect URIs list in the developer dashboard. If initializing on Android, android_package_name
must be specified instead and redirect_uri
should be left blank.android_package_name
link_token
to initialize Link on Android. Any package name specified here must also be added to the Allowed Android package names setting on the developer dashboard. When creating a link_token
for initializing Link on other platforms, android_package_name
must be left blank and redirect_uri
should be used instead.institution_data
routing_number
account_filters
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
depository
-type accountsaccount_subtypes
checking
, savings
, hsa
, cd
, money market
, paypal
, prepaid
, cash management
, ebt
, all
credit
credit
-type accountsaccount_subtypes
credit card
, paypal
, all
loan
loan
-type accountsaccount_subtypes
auto
, business
, commercial
, construction
, consumer
, home equity
, loan
, mortgage
, line of credit
, student
, other
, all
investment
investment
-type accounts (or brokerage
-type accounts for API versions 2018-05-22 and earlier).account_subtypes
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
institution_id
payment_initiation
payment_initiation
is included in the products
array. Either payment_id
or consent_id
must be provided.payment_id
payment_id
provided by the /payment_initiation/payment/create
endpoint.consent_id
consent_id
provided by the /payment_initiation/consent/create
endpoint.income_verification
income_verification
is included in the products
array.income_verification_id
income_verification_id
of the verification instance, as provided by /income/verification/create
.asset_report_id
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
/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
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
bank
and payroll
. Currently you can only specify one of these options.bank
, payroll
bank_income
income_verification
is included in the products
array and bank
is specified in income_source_types
.days_requested
1
731
enable_multiple_items
false
payroll_income
flow_types
payroll_digital_income
, payroll_document_income
is_update_mode
false
item_id_to_update
parsing_config
ocr
, fraud_risk
stated_income_sources
employer
category
OTHER
, SALARY
, UNEMPLOYMENT
, CASH
, GIG_ECONOMY
, RENTAL
, CHILD_SUPPORT
, MILITARY
, RETIREMENT
, LONG_TERM_DISABILITY
, BANK_INTEREST
pay_per_cycle
double
pay_annual
double
pay_type
GROSS
, NET
, or UNKNOWN
for a specified income sourceUNKNOWN
, GROSS
, NET
pay_frequency
UNKNOWN
, WEEKLY
, BIWEEKLY
, SEMI_MONTHLY
, MONTHLY
auth
auth_type_select _enabled
same_day_microdeposits_enabled
is set to true.false
automated _microdeposits_enabled
instant_match_enabled
false
.same_day _microdeposits_enabled
reroute_to_credentials
OPTIONAL
.OFF
, OPTIONAL
, FORCED
flow_type
auth_type_select_enabled
.FLEXIBLE_AUTH
update
account_selection _enabled
true
, enables update mode with Account Select for institutions that do not use OAuth, or that use OAuth but do not have their own account selection flow. For institutions that have an OAuth account selection flow (i.e. most OAuth-enabled institutions), update mode with Account Select will always be enabled, regardless of the value of this field.false
identity_verification
template_id
gave_consent
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.false
statements
start_date
date
user_token
/user/create
. Any Item created during the Link session will be associated with the user.investments
allow_unverified _crypto_wallets
true
, allow self-custody crypto wallets to be added without requiring signature verification. Defaults to false
.1const request: LinkTokenCreateRequest = {2 loading_sample: true3};4try {5 const response = await plaidClient.linkTokenCreate(request);6 const linkToken = response.data.link_token;7} catch (error) {8 // handle error9}
Response fields and example
link_token
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
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.date-time
request_id
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.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.link_token
link_token
from a previous invocation of /link/token/create
1const request: LinkTokenGetRequest = {2 link_token: linkToken,3};4try {5 const response = await plaidClient.linkTokenGet(request);6} catch (error) {7 // handle error8}
Response fields and example
link_token
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
expiration
metadata
/link/token/create
call.initial_products
products
specified in the /link/token/create
call.assets
, auth
, employment
, identity
, income_verification
, identity_verification
, investments
, liabilities
, payment_initiation
, standing_orders
, transactions
, transfer
webhook
webhook
specified in the /link/token/create
call.country_codes
country_codes
specified in the /link/token/create
call.US
, GB
, ES
, NL
, FR
, IE
, CA
, DE
, IT
, PL
, DK
, NO
, SE
, EE
, LT
, LV
, PT
language
language
specified in the /link/token/create
call.institution_data
routing_number
account_filters
account_filters
specified in the original call to /link/token/create
.depository
depository
-type accountsaccount_subtypes
checking
, savings
, hsa
, cd
, money market
, paypal
, prepaid
, cash management
, ebt
, all
credit
credit
-type accountsaccount_subtypes
credit card
, paypal
, all
loan
loan
-type accountsaccount_subtypes
auto
, business
, commercial
, construction
, consumer
, home equity
, loan
, mortgage
, line of credit
, student
, other
, all
investment
investment
-type accounts (or brokerage
-type accounts for API versions 2018-05-22 and earlier).account_subtypes
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
redirect_uri
specified in the /link/token/create
call.client_name
client_name
specified in the /link/token/create
call.request_id
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.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.public_token
public_token
, obtained from the Link onSuccess
callback or /sandbox/item/public_token/create
.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 error10}
Response fields and example
access_token
item_id
item_id
value of the Item associated with the returned access_token
request_id
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
.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.access_token
1// Generate a new access_token for an Item, invalidating the old one2const 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 datastore8 const accessToken = response.data.new_access_token;9} catch (error) {10 // handle error11}
Response fields and example
new_access_token
request_id
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.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.access_token
1// This endpoint is deprecated and not2// supported in the Beta libraries
Response fields and example
public_token
public_token
for the particular Item corresponding to the specified access_token
expiration
request_id
1{2 "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",3 "request_id": "Aim3b"4}