Authentication overview
Plaid secures access to its financial data APIs through a combination of API keys and short-lived tokens. Developers authenticate their applications to Plaid's backend using unique client IDs and secrets, which are provisioned through the Plaid Dashboard. This initial application-level authentication is distinct from user-level authentication, which occurs when an end-user connects their financial institution account via Plaid Link. Plaid's authentication framework is designed to comply with industry security standards, including SOC 2 Type II, PCI DSS, and ISO 27001, to protect sensitive financial data. The system employs various security measures to ensure data integrity and confidentiality, as detailed in Plaid's security documentation.
The authentication process typically involves several stages:
- Application Authentication: Your backend server authenticates to Plaid's API using your
client_idandsecret. This is required for almost all API calls. - User Authentication (via Plaid Link): End-users authenticate with their financial institution through the Plaid Link UI. Plaid Link handles the secure exchange of credentials and returns a
public_tokento your application. - Token Exchange: Your backend server exchanges the
public_tokenfor anaccess_tokenusing yourclient_idandsecret. Theaccess_tokenis a long-lived credential used to access specific user account data. - API Calls: Subsequent API calls to retrieve data (e.g., transactions, balances) use the
access_tokenand your application'sclient_idto identify both the application and the specific user's connected account.
This multi-layered approach ensures that both your application and the end-user's financial account are securely identified and authorized before any data transfer occurs. Plaid's official API reference provides comprehensive details on each endpoint's authentication requirements.
Supported authentication methods
Plaid primarily relies on API key-based authentication for server-to-server communication, complemented by temporary tokens for user consent flows. This system is designed to provide secure and auditable access to financial data while minimizing direct handling of sensitive user credentials by developer applications.
The core authentication methods supported by Plaid include:
- Client ID and Client Secret: These are your primary API keys, unique to your application and environment (Sandbox, Development, Production). They are used to authenticate your application with Plaid's API endpoints. The
client_ididentifies your application, while thesecretacts as a password, proving your application's identity. - Access Tokens: These are opaque, long-lived tokens generated after a user successfully connects their financial account through Plaid Link. An
access_tokenis specific to a user's connected item (a Plaid term for a financial institution account connection) and is used to retrieve data for that item. Unlike some OAuth 2.0 implementations, Plaid'saccess_tokensgenerally do not expire unless explicitly revoked by the user or application. - Public Tokens: These are short-lived, single-use tokens generated by Plaid Link after a user successfully authenticates their financial institution. A
public_tokenmust be exchanged for anaccess_tokenon your backend server within 30 minutes of creation. - Link Tokens: These are short-lived, single-use tokens generated by your server and passed to Plaid Link to initialize the user experience. A
link_tokendictates the user flow within Link, including which products are enabled and specific institution settings. They typically expire after 30 minutes.
Authentication method comparison
| Method | When to Use | Security Level |
|---|---|---|
| Client ID & Secret | Authenticating your application to Plaid's API; server-side calls only. | High (must be kept confidential on your server). |
| Access Token | Retrieving user-specific financial data after initial account connection. | High (long-lived, tied to specific item, stored securely server-side). |
| Public Token | Exchanging for an Access Token after user completes Plaid Link flow. | Medium (short-lived, single-use, client-side before server exchange). |
| Link Token | Initializing Plaid Link UI for user account connection. | Medium (short-lived, single-use, client-side for UI initialization). |
Getting your credentials
To begin using Plaid's APIs, you must first obtain your application credentials: a client_id and a secret. These are managed within the Plaid Dashboard, which serves as your central hub for application configuration, monitoring, and key management.
- Sign Up for a Plaid Account: Navigate to the Plaid quickstart guide and create a new developer account. This typically involves providing basic contact information and agreeing to Plaid's terms of service.
- Access the Plaid Dashboard: Once your account is created, log in to the Plaid Dashboard.
- Locate API Keys: In the dashboard, navigate to the 'Keys' section (often found under 'Team Settings' or 'API'). Here, you will find your
client_idandsecretfor each environment (Sandbox, Development, Production). - Environment-Specific Keys: Plaid provides separate key pairs for its Sandbox, Development, and Production environments. The Sandbox environment is for initial testing and development without real financial data. The Development environment allows you to test with a limited number of live financial connections, and the Production environment is for live applications handling real user data. Ensure you use the correct keys for your current environment.
- Key Rotation and Management: The Plaid Dashboard also allows you to rotate your API secrets for enhanced security. It is a best practice to periodically rotate these keys, especially if there's any suspicion of compromise. Plaid provides tools within the dashboard to facilitate this process, ensuring minimal disruption to your services.
For detailed instructions on obtaining and managing your credentials, refer to the Plaid API authentication overview.
Authenticated request example
This example demonstrates how to make a simple authenticated request to the Plaid API using Node.js to exchange a public_token for an access_token. This is a common first step after a user connects their account via Plaid Link.
const { Configuration, PlaidApi, Products, PlaidEnvironments } = require('plaid');
// 1. Configure Plaid client with your Client ID and Secret
const configuration = new Configuration({
basePath: PlaidEnvironments.development, // Use PlaidEnvironments.production for live apps
baseOptions: {
headers: {
'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
'PLAID-SECRET': process.env.PLAID_SECRET,
'Plaid-Version': '2020-09-14',
},
},
});
const client = new PlaidApi(configuration);
// 2. Assume you have a public_token obtained from Plaid Link (client-side)
const PUBLIC_TOKEN = 'public-development-xxxxxxxxx'; // Replace with an actual public_token
// 3. Exchange the public_token for an access_token
const exchangeToken = async () => {
try {
const request = {
public_token: PUBLIC_TOKEN,
};
const response = await client.itemPublicTokenExchange(request);
const accessToken = response.data.access_token;
const itemId = response.data.item_id;
console.log('Access Token:', accessToken);
console.log('Item ID:', itemId);
// Store accessToken and itemId securely in your database for future API calls
} catch (error) {
console.error('Error exchanging public token:', error.response.data);
}
};
exchangeToken();
In this example:
- The
Configurationobject is initialized with yourclient_idandsecret, typically sourced from environment variables for security. - The
PlaidApiclient is created, configured for either the Development or Production environment. - The
itemPublicTokenExchangeendpoint is called with thepublic_tokenreceived from the client-side Plaid Link integration. - The response contains the
access_tokenanditem_id, which are crucial for subsequent API calls to retrieve financial data for that specific user's connected account.
Further examples for various Plaid API calls can be found in the Plaid API quickstart guide.
Security best practices
Securely implementing Plaid authentication is critical due to the sensitive nature of financial data. Adhering to these best practices helps protect both your application and your users:
- Keep Client Secrets Confidential: Your
client_idandsecretare your application's primary credentials. Never expose them in client-side code (e.g., JavaScript in a web browser or mobile app). They should only be used on your secure backend servers. Store them as environment variables or in a secure secrets management system, not directly in your codebase. - Use HTTPS for All Communication: Always ensure all communication with Plaid's API and between your application's client and server components occurs over HTTPS. This encrypts data in transit, preventing eavesdropping and tampering. The use of TLS/SSL certificates is fundamental for secure web communication.
- Securely Store Access Tokens: Once you exchange a
public_tokenfor anaccess_token, store theaccess_tokensecurely in your database. Encrypting access tokens at rest is a strong recommendation. Associate eachaccess_tokenwith the corresponding user in your system. - Validate Webhooks: If you use Plaid webhooks for asynchronous event notifications, always validate their authenticity. Plaid signs its webhooks, and you should verify the signature using your webhook secret to ensure the notification genuinely came from Plaid and hasn't been tampered with. This prevents malicious actors from sending fake events. The Plaid webhook verification guide provides specific instructions.
- Implement Least Privilege: When generating Link tokens, specify only the necessary Plaid products (e.g.,
transactions,auth) that your application requires. This limits the scope of data access to what is strictly needed for your application's functionality. - Regularly Rotate API Keys: Periodically rotate your Plaid API secrets through the Plaid Dashboard. This minimizes the risk associated with a compromised key, as an old key will eventually become invalid. Establish a schedule for key rotation as part of your security operations.
- Monitor API Usage and Errors: Regularly review your API logs and monitor for unusual activity or excessive errors. This can help detect potential unauthorized access attempts or misconfigurations early.
- Isolate Environments: Use distinct
client_idandsecretpairs for your Sandbox, Development, and Production environments. Never use production keys in development or testing. - Client-Side Security for Plaid Link: While Plaid Link handles much of the complexity, ensure your client-side implementation (e.g., React Native SDK, iOS SDK) is up-to-date and correctly configured to prevent common vulnerabilities like cross-site scripting (XSS) that could intercept
public_tokens.