Glossary
A glossary of Plaid terminology
Tokens, identifiers, and keys
Plaid tokens are in the format [type]-[environment]-[uuid]
, where the type may be public
, access
, link
, or asset-report
, and the environment may be sandbox
, development
, or 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
An 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 /item/remove
.
Asset report token
An 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/create
. An 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 /asset_report/remove
.
Client ID
Your 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
An 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 /item/get
and /item/public_token/exchange
.
Link token
A 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
The 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
A 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/token/create
or /processor/stripe/bank_account_token/create
and providing an access_token
. The processor_token
does not expire. Once successfully passed to the processor, it can be safely deleted from your database.
Public token
A 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
A 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.
Secret
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
A 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 user_token
.
Environments
Development
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
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. Plaid will soon add the ability to test with real data for free directly in Production.
Sandbox
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
Account
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 INVALID_ACCOUNT_ID
.
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 access_token
.
Dashboard
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.
Item
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 item_id
.
Link
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.
Plaid Consumer Reporting Agency
Plaid Consumer Reporting Agency (or Plaid CRA) is focused on building solutions for customers who want ready-made credit risk insights from consumer-permissioned cash flow data. To subscribe to updates about Plaid Consumer Reporting Agency, Inc. complete the CRA interest form. Plaid's current products described in the docs, including Assets and Income, are provided by Plaid, Inc., which is not a consumer reporting agency.