A glossary of Plaid terminology
Tokens, identifiers, and keys
Plaid tokens are in the format
[type]-[environment]-[uuid], where the type may be
asset-report, and the environment may be
production; a token will only ever be valid within the environment it was created. The UUID is a 32 character hexadecimal string in the pattern of 8-4-4-4-12 characters and conforms to the RFC 4122 standard.
access_token is a token used to make API requests related to a specific Item. You will typically obtain an
access_token by calling
/item/public_token/exchange. For more details, see the Token exchange flow. An
access_token does not expire, although it may require updating, such as when a user changes their password, or when working with European institutions that comply with PSD2's 90-day consent window. For more information, see When to use update mode. Access tokens should always be stored securely, and associated with the user whose data they represent. If compromised, an
access_token can be rotated via
/item/access_token/invalidate. If no longer needed, it can be revoked via
Asset report token
asset_report_token is a token used to make API requests related to a specific Asset Report. You will obtain an
asset_report_token by calling
asset_report_token does not expire, and should always be stored securely, and should be associated in your database with the user whose data it represents. If compromised or no longer needed, an
asset_report_token can be revoked via
client_id is an identifier required by the Plaid API. It must be provided for almost all API calls. Your client ID can be found on the Dashboard. Your client ID uniquely identifies your team and will be the same for all API calls made on behalf of your organization, regardless of the API environment or the specific individual using the API.
item_id uniquely identifies a Plaid Item. The
item_id is part of the response for API endpoints that operate on a specific Item, including most product endpoints, as well as
link_token is a token used to initialize Link, and must be provided any time you are presenting your user with the Link interface. You can obtain a Link token by calling
/link/token/create. For more details, see the the Token exchange flow. A
link_token expires after 4 hours (or after 30 minutes, when being used with update mode).
Link session ID
link_session_id is a unique ID included in all Link callbacks. For faster issue resolution, the
link_session_id should be included when contacting Support regarding a specific Link session.
processor_token is a token used by a Plaid partner to make API calls on your behalf. You can obtain a
processor_token by calling
/processor/stripe/bank_account_token/create and providing an
processor_token does not expire. Once successfully passed to the processor, it can be safely deleted from your database.
public_token is a token obtained from Link's
onSuccess callback. This token can be exchanged for an
access_token by calling
/item/public_token/exchange. For more details, see the Token exchange flow. A
public_token expires after 30 minutes.
request_id is a unique ID returned as part of the response body for every Plaid API response (except for API endpoints that return binary data, in which case the
request_id will be found in the header). The
request_id can be used to look up the request on the Activity Log and should be included when contacting Support regarding a specific API call.
Your secret is used to authenticate calls to the Plaid API. Secrets can be found on the dashboard. Your secret should be kept secret and rotated if it is ever compromised. For more information, see rotating keys.
user_token is used when working with Plaid's Income or Employment APIs. It is used to associate income data from multiple sources with a single user and must be provided when initializing
/link/token/create for an Income Verification flow. A
user_token is created by calling
/user/create and does not expire. Ensure that you store the
user_token along with your user's identifier in your database, as it is not possible to retrieve a previously created
Development (https://development.plaid.com) is one of three Plaid environments on which you can run your code, along with Sandbox and Production. Like Production, the Development environment uses real world data, but like Sandbox, API calls in Development are not billed. You can create up to 100 Items in Development, and these Items cannot be moved to Production. If you run out of test Items, you may file a support ticket. For more information, see Testing with live data using Development.
To simplify the development process, Plaid will be replacing the Development environment with the ability to test with real data for free directly in Production. On June 20, 2024, the Plaid Development environment will be decommissioned, and all Development Items will be removed. You may continue to test on the Development environment until this time.
Production (https://production.plaid.com) is one of three Plaid environments on which you can run your code, along with Sandbox and Development. While Sandbox and Development are intended as test environments, Production is intended for production code. It uses real world data, and API calls are billed.
The Sandbox (https://sandbox.plaid.com) is one of three Plaid environments on which you can run your code, along with Development and Production. Sandbox is a free test environment in which no real data can be used. The Sandbox environment also offers a number of special Sandbox-only capabilities to make testing easier. For more information, see Sandbox.
Other Plaid terminology
An account is a single account held by a user at a financial institution; for example, a specific checking account or savings account. A user may have more than one account at a given institution; the overall object that contains all of these accounts is the Item. Each account is uniquely identified by an
account_id, which will not change, unless Plaid is unable to reconcile the account with the data returned by the financial institution; for more information, see
Plaid will automatically detect when an account is closed, and will no longer return the
account_id for a closed account. If an
access_token is deleted, and the same credentials that were used to generate that
access_token are used to generate a new
access_token on a later date, the new
account_id will be different from the
account_id associated with the original
The Plaid Dashboard is used to manage your Plaid developer account, configure your account for OAuth, and to obtain keys and secrets. The Dashboard also contains a number of useful features, including troubleshooting tools, activity and usage logs, billing data, details and status for supported institutions, and the ability to request additional products or environments or to submit a support ticket. It can be found at dashboard.plaid.com. For more information, see Your Plaid developer account.
An Item represents a login at a financial institution. A single end-user of your application might have accounts at different financial institutions, which means they would have multiple different Items. 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. Each Item linked within your application will have a corresponding
access_token, which is a token that you can use to make API requests related to that specific Item.
Two Items created for the same set of credentials at the same institution will be considered different and not share the same
Link is Plaid's client-side, user-facing UI that allows end users to connect their financial institution account to your application. For more information, see Link.