How to Handle Plaid Link Token Expiration in Your Fintech App
Plaid link tokens expire after 4 hours when created for new account connections, and your fintech app needs to handle that expiration gracefully or users will see errors when trying to link their bank accounts.
The link token is what you pass to Plaid Link (the modal where users select their bank and log in). If a user opens your app, you generate a link token, then they get distracted and come back 5 hours later to click "Connect Bank Account," the token is stale. Plaid will reject it, and without proper handling, your user sees a broken flow.
This happens more often than you might expect. Users open your app on mobile, switch to another app, and return later. They start the connection process on desktop, take a call, then resume. Every one of those scenarios can cross the 4-hour boundary.
Why Plaid Link Tokens Expire
Link tokens are short-lived by design for security. They contain configuration about what your app is requesting (accounts, transactions, identity data) and which institution environments to support. A token that lives indefinitely is a broader attack surface.
A link token created to generate a public token that will be exchanged for a new access token expires after 4 hours. If you're using Link in update mode (re-authenticating an existing connection), the expiration behavior differs, but the 4-hour window applies to the most common case: onboarding a new user.
Plaid returns an expiration timestamp in ISO 8601 format when you create the token. You can check that value, but in practice, your backend should generate a fresh token on demand rather than trying to cache and reuse one.
Detecting Expiration Before Initializing Link
The cleanest approach is to generate the link token immediately before you open Plaid Link, not when the page first loads. This keeps the token fresh and avoids expiration edge cases altogether.
Don't do this:
// Page load const linkToken = await fetch('/api/plaid/create-link-token').then(r => r.json()); // Much later, user clicks button document.getElementById('connect-bank').addEventListener('click', () => { const handler = Plaid.create({ token: linkToken.link_token, // May be expired by now onSuccess: handleSuccess, }); handler.open(); });
Do this instead:
document.getElementById('connect-bank').addEventListener('click', async () => { // Generate token right before opening Link const linkToken = await fetch('/api/plaid/create-link-token').then(r => r.json()); const handler = Plaid.create({ token: linkToken.link_token, onSuccess: handleSuccess, }); handler.open(); });
This pattern eliminates expiration as a concern for most users. The token is created seconds before it's used.
Handling Expiration When You Must Generate Early
Sometimes you need to generate the token earlier, for example if you're embedding the Plaid Link flow in a mobile app where network latency matters, or if you want to preload the Link SDK for performance.
In those cases, check the expiration field returned when you create the token, and regenerate if needed:
let linkTokenData = null; async function getValidLinkToken() { if (!linkTokenData || new Date(linkTokenData.expiration) <= new Date()) { // Token missing or expired, fetch a new one const response = await fetch('/api/plaid/create-link-token'); linkTokenData = await response.json(); } return linkTokenData.link_token; } document.getElementById('connect-bank').addEventListener('click', async () => { const token = await getValidLinkToken(); const handler = Plaid.create({ token: token, onSuccess: handleSuccess, }); handler.open(); });
Your backend /api/plaid/create-link-token endpoint calls Plaid's /link/token/create and returns both link_token and expiration. The frontend checks the timestamp and decides whether to reuse or request a fresh one.
Backend Token Generation
Your backend endpoint should create the link token by calling Plaid's /link/token/create. Here's a minimal Node.js example using the official Plaid client library:
const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid'); const configuration = new Configuration({ basePath: PlaidEnvironments.sandbox, // or production baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, }, }, }); const plaidClient = new PlaidApi(configuration); app.post('/api/plaid/create-link-token', async (req, res) => { try { const response = await plaidClient.linkTokenCreate({ user: { client_user_id: req.user.id }, client_name: 'Your App Name', products: ['transactions'], country_codes: ['US'], language: 'en', }); res.json({ link_token: response.data.link_token, expiration: response.data.expiration, }); } catch (error) { console.error('Error creating link token:', error); res.status(500).json({ error: 'Failed to create link token' }); } });
The client_user_id should be a stable identifier for your user. Plaid uses it for analytics and debugging, but it doesn't affect token expiration.
Never cache link tokens across users. Each user gets their own token tied to their client_user_id. Reusing tokens between users or sessions will cause Plaid to reject the public token exchange later.
What Happens If You Use an Expired Token
If you pass an expired link token to Plaid.create(), the Link modal will fail to initialize. The exact error depends on the SDK version, but you'll typically see a network error or an invalid token message in the console.
Plaid doesn't return a user-friendly error screen in this case because the token is validated before the UI renders. Your app will appear broken: the button does nothing, or a loading spinner hangs.
This is why generating the token on demand is the better pattern. You avoid silent failures and don't need complex error handling in the frontend.
Edge Case: Update Mode and Link Customization
A link token created for an existing Item (such as when updating an existing access token by launching Link in update mode) expires after 4 hours. The expiration window is the same, but the use case is different.
Update mode is when you already have an access_token for a user's bank connection, but it's no longer valid (the bank requires re-authentication, or the user changed their password). You create a link token with the access_token included in the request, then open Link so the user can log in again.
Same expiration rules apply: generate the token right before you need it.
If you're using hosted Link (where Plaid generates a URL you send to the user via email or SMS),
you can customize the duration using the hosted_link.url_lifetime_seconds option in the request.
The default is 7 days for email, 1 day for SMS, and 30 minutes for links not sent via Plaid Link delivery. For most embedded implementations, you don't use hosted Link and the 4-hour expiration is fixed.
Mobile App Considerations
Mobile apps face the same expiration behavior, but the UX patterns differ. If you're using the Plaid React Native SDK or iOS/Android native SDKs, generate the link token when the user taps the button to connect their bank, not when the screen loads.
Mobile apps often sit in the background for hours or days. A token generated on screen mount will almost certainly expire before the user acts.
// React Native example import { PlaidLink } from 'react-native-plaid-link-sdk'; const BankConnectionScreen = () => { const [linkToken, setLinkToken] = useState(null); const handlePress = async () => { // Generate token on button press const response = await fetch('https://yourapi.com/plaid/create-link-token'); const data = await response.json(); setLinkToken(data.link_token); }; return ( <> <Button title="Connect Bank" onPress={handlePress} /> {linkToken && ( <PlaidLink tokenConfig={{ token: linkToken }} onSuccess={handleSuccess} onExit={handleExit} /> )} </> ); };
This keeps the token fresh and avoids the scenario where a user backgrounds your app mid-flow.
References
Stardelite builds fintech products with secure, reliable integrations to banking platforms like Plaid, Stripe, and Dwolla. If you're building a financial app and need help with compliance, architecture, or implementation, get in touch.