Composio connects AI agents to Plaid so they can look up banks, read accounts, balances and transactions, and work with transfers and payments.
Plaid has no sign-in screen here. You connect by pasting keys from your Plaid account into Composio. This guide shows where to find each key and where to paste it. You will see two modes: Sandbox is Plaid's free test mode with fake bank data, and Production uses real bank data.
You will use up to three values:
Client ID: identifies your Plaid account. Always needed.
Secret: the password for your Plaid account. Always needed. Sandbox and Production each have their own.
Access token: points to one linked bank login. Only needed for tools that read bank data.
Part 1: Get your Plaid credentials
Step 1: Copy your keys
Sign in to the Plaid Dashboard at dashboard.plaid.com. In the left menu, open Build and select Keys.
Copy the Client ID. You use the same Client ID for Sandbox and Production.
Copy the secret for the mode you want. Use the Sandbox secret for testing and the Production secret for real bank data. Select the eye icon to show a secret, or the copy icon to copy it.
Keep both values ready. You paste them into Composio in Part 2. The secret must match the mode you choose there. A Sandbox secret with Production selected fails on every call.

Step 2: Check whether you need an access token
Your Client ID and secret only prove who you are. They do not point to any bank account. To read bank data, Plaid needs one more value called an access token. Each access token belongs to one linked bank login. Plaid calls that linked bank login an Item.
You do not need an access token for tools that are not about one person's bank, such as searching or listing institutions.
You need an access token for tools that read one person's bank data: accounts, balances, transactions, identity, liabilities, investments and statements.
One Composio connection stores one access token, so it works with one linked bank. For three linked banks, create three connections. Not sure yet? Skip the token for now. You can add it later with Part 2, Step 4.
Step 3: Get an access token (skip if you do not need one)
Open Plaid Link in your app. Plaid Link is Plaid's pop-up where a person picks their bank and signs in. To open it you need a link token. You can create one with the
PLAID_CREATE_LINK_TOKENtool on a connection that has no access token yet.The person signs in to their bank inside Plaid Link. When they finish, Plaid gives your app a short-lived value called a
public_token.Send the
public_tokento Plaid from your server withPOST /item/public_token/exchange. Plaid replies with theaccess_token. This is the value you paste into Composio.
You can tell the mode from the token. Sandbox tokens start with access-sandbox-. Production tokens start with access-production-. Only testing? Part 2, Step 4 shows how to create a Sandbox access token with two commands, without building Plaid Link.
Part 2: Connect Plaid in Composio
Step 1: Create an auth config
In the Composio dashboard, open Auth Configs and select Create. An auth config is the saved setup that tells Composio how to connect to Plaid. You create it once and reuse it for every account you connect.
Search for Plaid and select the toolkit with the API Key badge.

Enter a Config Name and select Next. The name is only a label to help you find this setup later.

Keep API Key selected. It is the only way to connect Plaid. Select Create Auth Config.

The new auth config opens with status Enabled and no connected accounts yet.

Step 2: Connect your account
Open the auth config you just created and select Connect Account. A form opens in a new browser window. Fill in the fields in the order below.
Environment: choose Sandbox for test data or Production for real bank data. Sandbox is selected by default.
Client ID: paste the Client ID you copied in Part 1, Step 1.
Secret: paste the secret for the Environment you chose. A Sandbox secret only works with Sandbox.
Item access token: optional. Paste the access token from Part 1, Step 3 if you have one. Leave it empty if you only need institution tools, or if you plan to add it later with Step 4.
Legacy user token: leave this empty. It is only for Plaid integrations created before December 10, 2025 that use Plaid's old User API.
Select Connect Account to save the connection.

Step 3: Confirm the connection
Go back to the auth config page. Under Connected Accounts, the new account shows the status Active.
Run one institution tool, such as searching institutions. If it returns results, your Client ID and secret are correct.
If you added an access token, run the get accounts tool. If it returns the bank's accounts, the token is correct.
Do not rely on the Active status alone. Composio cannot test Plaid keys when you connect, because Plaid has no way to check keys without making a real call. A connection can show Active even with a wrong secret. The tool calls above are the real test.

Step 4: Add the access token to an existing connection
Use this step when the connection already exists and you want to add an access token, or swap it for a different one. You do not need to delete the connection or create a new one. The dashboard has no edit button for this, so you send one request to the Composio API.
It has two parts. First you get an access token. Follow the Sandbox part if you are testing, or the Production part if you use real bank data. Then you send that token to Composio. That last part is the same for both.
Sandbox: get an access token
Sandbox uses test data, so Plaid can create a token for you with two commands. No bank sign-in is needed.
First, create a test public_token. Run the command below in a terminal. Replace YOUR_CLIENT_ID and YOUR_SANDBOX_SECRET with the values from the Plaid Keys page.
Do not change the institution_id line. The value ins_109508 is the ID of First Platypus Bank, a fake bank that Plaid provides for testing in Sandbox.
curl -X POST "https://sandbox.plaid.com/sandbox/public_token/create" \
-H "Content-Type: application/json" \
-d '{
"client_id": "YOUR_CLIENT_ID",
"secret": "YOUR_SANDBOX_SECRET",
"institution_id": "ins_109508",
"initial_products": ["transactions"]
}'Plaid replies with a public_token that starts with public-sandbox-. Copy it. It stops working after 30 minutes, so use it right away.
Next, exchange the public_token for an access token. Run the command below. Replace YOUR_PUBLIC_TOKEN with the value you just copied. Use the same Client ID and Sandbox secret as before.
curl -X POST "https://sandbox.plaid.com/item/public_token/exchange" \
-H "Content-Type: application/json" \
-d '{
"client_id": "YOUR_CLIENT_ID",
"secret": "YOUR_SANDBOX_SECRET",
"public_token": "YOUR_PUBLIC_TOKEN"
}'Plaid replies with an access_token that starts with access-sandbox-. Copy it. You now have a Sandbox access token. Skip the Production part and go to the last part of this step.
Production: get an access token
Production uses real bank data, so no command can create a public_token for you. A real person must sign in to their bank through Plaid Link in your app. When they finish, your app receives the public_token. Part 1, Step 3 explains this.
Then exchange the public_token for an access token. Run the command below. It uses production.plaid.com and your Production secret. Replace YOUR_CLIENT_ID, YOUR_PRODUCTION_SECRET and YOUR_PUBLIC_TOKEN with your own values.
curl -X POST "https://production.plaid.com/item/public_token/exchange" \
-H "Content-Type: application/json" \
-d '{
"client_id": "YOUR_CLIENT_ID",
"secret": "YOUR_PRODUCTION_SECRET",
"public_token": "YOUR_PUBLIC_TOKEN"
}'Plaid replies with an access_token that starts with access-production-. Copy it.
Sandbox and Production: add the token to the connection
This part is the same for both modes. First, find the connected account ID. Open the auth config in the Composio dashboard. Under Connected Accounts, copy the value in the Connected Account ID column. It starts with ca_.
Then send the access token to Composio. Run the command below. Replace ca_YOUR_ID with the connected account ID. Replace YOUR_COMPOSIO_API_KEY with a key from the API Keys page in the Composio dashboard. Replace YOUR_ACCESS_TOKEN with the access token you copied. The token must match the connection: a Sandbox token for a Sandbox connection, a Production token for a Production connection. Leave API_KEY and generic_token as they are. API_KEY is the connection type, not your key, and generic_token is the name of the field where Composio stores the Plaid access token.
curl -X PATCH \
"https://backend.composio.dev/api/v3.1/connected_accounts/ca_YOUR_ID" \
-H "x-api-key: YOUR_COMPOSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connection": {
"state": {
"authScheme": "API_KEY",
"val": { "generic_token": "YOUR_ACCESS_TOKEN" }
}
}
}'Composio replies with success set to true. Only the access token changes. Your Client ID, secret and Environment stay the same.
Last, check that it worked. Run the get accounts tool on this connection. If it returns the bank's accounts, the token is saved and working. To remove the token later, send the same command with null in place of the token.
Before using Production
Plaid must approve your account for Production, and for each product you use.
Production secrets and access tokens read real bank data. Store them only in Composio connection fields, never in prompts or tool inputs.
Transfer and payment tools move real money in Production. Test them in Sandbox first. The toolkit includes Sandbox-only tools to simulate transfers, payments and webhooks.
Frequently asked questions
Do I need to choose scopes for Plaid?
No. Plaid connects with API keys, so there are no scopes to pick. What a connection can do depends on the Plaid products enabled on your Plaid account, and on whether the connection has an access token.
Why does every call fail with INVALID_API_KEYS?
Plaid returns this when the Client ID or secret is not valid for the mode you are using. The usual cause is a Sandbox secret on a Production connection, or the reverse. Create a new connection with the secret that matches the Environment.
Institution tools work, but account and transaction tools fail. Why?
The connection has no access token. Institution tools only need your keys. Account, balance and transaction tools also need the access token of a linked bank. Add one with Part 2, Step 4.
Why do I get INVALID_ACCESS_TOKEN?
The access token is wrong, or it belongs to the other mode. A token that starts with access-sandbox- only works on a Sandbox connection. A token that starts with access-production- only works on a Production connection.
Why do I get INVALID_PRODUCT?
Plaid returns this when your Plaid account does not have access to the product that the tool uses. Enable the product in the Plaid Dashboard, or request access from Plaid.
What does ITEM_LOGIN_REQUIRED mean?
The person's bank login has changed or expired, so Plaid needs them to sign in again. Open Plaid Link in update mode for that bank. After they sign in, the same access token works again. You do not need to change anything in Composio.
Can I add or change the access token after I connect?
Yes. Follow Part 2, Step 4. You do not need to create a new connection.
Can one connection work with more than one bank?
No. One connection stores one access token, and one access token belongs to one linked bank. Create one connection for each linked bank.
My connection shows Active, but tools fail. Why?
Active only means the connection was saved. Composio cannot test Plaid keys when you connect. Run an institution tool to check that your keys are correct.