Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 06:00 UTC
| 1 | ## How do I connect Plaid with API keys? |
| 2 | |
| 3 | Plaid has no sign-in screen. You connect by pasting keys from your Plaid account into a Composio connection. Each connection uses one Plaid environment: **Sandbox** for Plaid's test data or **Production** for real bank data. |
| 4 | |
| 5 | You use up to three values: |
| 6 | |
| 7 | - **Client ID**: identifies your Plaid account. Always required. |
| 8 | - **Secret**: required. Sandbox and Production each have their own secret. |
| 9 | - **Access token**: points to one linked bank login, which Plaid calls an Item. Only needed for tools that read one person's bank data. |
| 10 | |
| 11 | ### Get your Plaid keys |
| 12 | |
| 13 | 1. Sign in to the [Plaid Dashboard](https://dashboard.plaid.com/). In the left menu, open **Build** → **Keys**. |
| 14 | 2. Copy the **Client ID**. It's the same for Sandbox and Production. |
| 15 | 3. Copy the secret for the environment you'll use. A Sandbox secret on a Production connection fails on every call, and the reverse. |
| 16 | |
| 17 |  |
| 18 | |
| 19 | ### Decide whether you need an access token |
| 20 | |
| 21 | Institution tools, such as searching or listing institutions, work with only the Client ID and secret. Tools that read accounts, balances, transactions, identity, liabilities, investments, or statements also need an access token. |
| 22 | |
| 23 | One connection stores one access token, so it works with one linked bank. For three linked banks, create three connections. If you're not sure, skip the token now and add it later. |
| 24 | |
| 25 | To get an access token: |
| 26 | |
| 27 | 1. Open Plaid Link in your app. Plaid Link is Plaid's pop-up where a person picks their bank and signs in. You need a link token to open it; you can create one with the `PLAID_CREATE_LINK_TOKEN` tool on a connection that doesn't have an access token yet. |
| 28 | 2. When the person finishes signing in, Plaid gives your app a short-lived `public_token`. |
| 29 | 3. From your server, send it to Plaid's `POST /item/public_token/exchange` endpoint. Plaid returns the `access_token`. |
| 30 | |
| 31 | Sandbox tokens start with `access-sandbox-` and Production tokens with `access-production-`. |
| 32 | |
| 33 | ### Create the auth config and connect |
| 34 | |
| 35 | 1. In the [Composio dashboard](https://dashboard.composio.dev/~/project/auth-configs?utm_source=docs&utm_medium=content&utm_campaign=toolkits-plaid), go to **Auth Configs** → **Create**, select **Plaid** (API Key is the only method), and click **Create Auth Config**. |
| 36 | |
| 37 |  |
| 38 | |
| 39 |  |
| 40 | |
| 41 | 2. Open the auth config and click **Connect Account**. |
| 42 | 3. Fill in the form: |
| 43 | - **Environment**: `sandbox` (the default) or `production`. |
| 44 | - **Client ID** and **Secret**: the values from the Keys page. The secret must match the environment. |
| 45 | - **Item access token**: optional. Leave it empty if you only need institution tools. |
| 46 | - **Legacy user token**: leave empty. It's only for Plaid integrations created before December 10, 2025 that use Plaid's old User API. |
| 47 | |
| 48 |  |
| 49 | |
| 50 | 4. Click **Connect Account**. The account shows **Active** on the auth config's **Connected Accounts** tab. |
| 51 | |
| 52 | **Active** only means the connection was saved. Composio can't check Plaid keys when you connect, so a wrong secret still shows Active. Run an institution search tool to test the Client ID and secret, and the get accounts tool to test the access token. |
| 53 | |
| 54 | See [custom auth configs](/docs/auth-configuration/custom-auth-configs) for the general flow. |
| 55 | |
| 56 | ### Create a Sandbox access token without Plaid Link |
| 57 | |
| 58 | In Sandbox, two calls create a token for First Platypus Bank (`ins_109508`), Plaid's test bank. No bank sign-in is needed. |
| 59 | |
| 60 | ```bash |
| 61 | curl -X POST "https://sandbox.plaid.com/sandbox/public_token/create" \ |
| 62 | -H "Content-Type: application/json" \ |
| 63 | -d '{ |
| 64 | "client_id": "YOUR_CLIENT_ID", |
| 65 | "secret": "YOUR_SANDBOX_SECRET", |
| 66 | "institution_id": "ins_109508", |
| 67 | "initial_products": ["transactions"] |
| 68 | }' |
| 69 | ``` |
| 70 | |
| 71 | Plaid returns a `public_token` starting with `public-sandbox-`. It expires after 30 minutes. Exchange it right away: |
| 72 | |
| 73 | ```bash |
| 74 | curl -X POST "https://sandbox.plaid.com/item/public_token/exchange" \ |
| 75 | -H "Content-Type: application/json" \ |
| 76 | -d '{ |
| 77 | "client_id": "YOUR_CLIENT_ID", |
| 78 | "secret": "YOUR_SANDBOX_SECRET", |
| 79 | "public_token": "YOUR_PUBLIC_TOKEN" |
| 80 | }' |
| 81 | ``` |
| 82 | |
| 83 | The response contains an `access_token` starting with `access-sandbox-`. In Production, a real person has to sign in through Plaid Link; then call the same exchange endpoint on `https://production.plaid.com` with your Production secret. |
| 84 | |
| 85 | ### Add or replace the access token on an existing connection |
| 86 | |
| 87 | You don't need a new connection. The dashboard has no edit button for this, so [update the connected account](/reference/api-reference/connected-accounts/patchConnectedAccountsByNanoid) through the API. Copy the connected account ID (starts with `ca_`) from the **Connected Accounts** tab, and send a body that sets `connection.state.authScheme` to `API_KEY` and `connection.state.val.generic_token` to the Plaid access token. `generic_token` is the field that stores the access token, and the token must match the connection's environment. Only the token changes; the Client ID, secret, and environment stay the same. To remove the token, send `null` as its value. Run the get accounts tool to confirm it works. |
| 88 | |
| 89 | ### Before using Production |
| 90 | |
| 91 | - Plaid must approve your account for Production and for each product you use. |
| 92 | - Production secrets and access tokens read real bank data. Store them only in Composio connection fields, never in prompts or tool inputs. |
| 93 | - Transfer and payment tools move real money in Production. Test them in Sandbox first; the toolkit includes Sandbox-only tools that simulate transfers, payments, and webhooks. |
| 94 | |
| 95 | ## Do I need to choose scopes for Plaid? |
| 96 | |
| 97 | No. Plaid uses API keys, so there are no scopes. What a connection can do depends on the Plaid products enabled on your Plaid account and on whether the connection has an access token. |
| 98 | |
| 99 | ## Why does every Plaid call fail with `INVALID_API_KEYS`? |
| 100 | |
| 101 | The Client ID or secret isn't valid for the connection's environment. 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. |
| 102 | |
| 103 | ## Why do institution tools work but account and transaction tools fail? |
| 104 | |
| 105 | The connection has no access token. Institution tools need only your keys; account, balance, and transaction tools also need the access token of a linked bank. Add one to the existing connection as described above. |
| 106 | |
| 107 | ## Why do I get `INVALID_ACCESS_TOKEN` from Plaid? |
| 108 | |
| 109 | The access token is wrong or belongs to the other environment. A token starting with `access-sandbox-` works only on a Sandbox connection, and one starting with `access-production-` only on a Production connection. |
| 110 | |
| 111 | ## Why do I get `INVALID_PRODUCT` from Plaid? |
| 112 | |
| 113 | Your Plaid account doesn't have access to the product the tool uses. Enable the product in the Plaid Dashboard or request access from Plaid. |
| 114 | |
| 115 | ## What does `ITEM_LOGIN_REQUIRED` mean? |
| 116 | |
| 117 | The person's bank login 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, and nothing changes in Composio. |