> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meld.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Step 1: Create a Connect Token
The first step in linking a customer's bank account is creating a **connect token**. A connect token is a short-lived JWT that authorizes the Meld Connect Widget to start a connection session for a specific customer with a specific set of products and regions. This page walks developers through generating a token, configuring it correctly, and using the response to launch the widget in Step 2.
## Before you begin
* You have a Meld sandbox or production API key
* You have decided which [products](/docs/bank-linking/creating-connections/create-a-connect-token/supported-bank-linking-products) you need (you can also use [optional products](/docs/bank-linking/creating-connections/create-a-connect-token/optional-products))
* You know the [regions](/docs/bank-linking/creating-connections/create-a-connect-token/supported-bank-linking-products) your customers bank in, or are comfortable leaving regions unset
* Your server is calling the endpoint — **never call this endpoint from the browser or mobile client**, the API key is a secret
## Create the token
Send a `POST` request to `{api_base_url}/bank-linking/connect/start` using your API key. The response contains the `connectToken` you will use in [Step 2: Launch the widget](/docs/bank-linking/creating-connections/launch-the-widget).
For the full request and response schema, refer to the [Bank Linking — Create Connect Token API reference](/api-reference/bank-linking).
The connect token is used only while the user is making the connection to their bank and **expires after 3 hours**. You do not have to persist it — once the connection completes it cannot be reused. To track a connection over time, use the `customerId` returned in the response, or the `externalCustomerId` you optionally pass in.
Be deliberate about the regions and products you request. In Step 3, when the user selects their institution, only institutions that support **all** requested products and are in one of the requested regions appear in the widget. Choosing too many products or too few regions can dramatically shrink the institution list. If you don't know the region in which your customer banks, omit the `regions` parameter entirely.
**Disabling / re-enabling service providers**
If you disable a service provider in the Meld dashboard and later re-enable it (with the same or different credentials), use new `customerId` / `externalCustomerId` values for subsequent connections. Reusing prior identifiers can result in an `Error creating user` when the customer selects an institution.
## Skipping or prepopulating the Meld picker
If you already know which institution the user wants to link (for example, you collect that in your own UI), you have two options to make the flow more seamless:
1. **Prepopulate the search box.** Pass the institution name as a string when creating the connect token. The Meld picker autofills the search input so matching institutions appear by default. The user can still edit the search string.
2. **Skip the picker entirely.** Pass the `institutionId` corresponding to the user's bank. This skips the Meld picker screen and sends the user straight to the institution login.
To resolve an institution name to a Meld `institutionId`, use the [/institutions endpoint](/api-reference/bank-linking). Note that for MX, not all institutions that support transactions also support historical transactions, so `HISTORICAL_TRANSACTIONS` appears as a separate product in the institution search response. However, when listing products in `/connect/start`, pass `TRANSACTIONS` only — `HISTORICAL_TRANSACTIONS` is not a valid value for the products array on `/connect/start`.
A key part of building the request body is the list of products. For more information on the available products and which to request, see [Supported Bank Linking Products](/docs/bank-linking/creating-connections/create-a-connect-token/supported-bank-linking-products).
## Sample request
```bash theme={null}
curl --location 'https://api-sb.meld.io/bank-linking/connect/start' \
--header 'Meld-Version: 2022-11-10' \
--header 'Content-Type: application/json' \
--header 'Authorization: BASIC ***Redacted API Key***' \
--data '{
"externalCustomerId": "testCustomer",
"products": [
"BALANCES",
"OWNERS",
"IDENTIFIERS",
"TRANSACTIONS",
"INVESTMENT_HOLDINGS",
"INVESTMENT_TRANSACTIONS"
],
"regions": ["US", "CA"],
"institutionSearchString": "Fidelity"
}'
```
## Sample response
```json theme={null}
{
"id": "WQ46XEVzT14vrrDq6LSJVg",
"connectToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZWRpcmVjdCI6dHJ1ZSwicmVnaW9ucyI6WyJVUyIsIkNBIl0sImlzcyI6Im1lbGQuaW8iLCJjb25uZWN0aW9uIjoiV1E0NlhFVnpUMTR2cnJEcTZMU0pFZCIsImV4cCI6MTY4Njc5ODkzMywiaWF0IjoxNjg2Nzg0NTMzLCJhY2NvdW50IjoiVzlrYmtSbWU5VlQyaXo2cUFTZkFmMiIsImN1c3RvbWVyIjoiV1E0NlhEcllZTVlyZTlSQmt3YXl5USIsInByb2R1Y3RzIjpbIlRSQU5TQUNUSU9OUyIsIkJBTEFOQ0VTIiwiSURFTlRJRklFUlMiLCJPV05FUlMiXSwicm91dGluZ1Byb2ZpbGUiOiJXR3ZGWHRYYkRvQ2VXc3hVdHVpeFB5In0.jAwpUokwkSKi7BTwKJOY_Y6XAPv_O8yOi6mVaUKxnMI",
"customerId": "WQ46XDrYYMYre9RBkwayyZ",
"externalCustomerId": "testCustomer",
"widgetUrl": "https://institution-connect-sb.meld.io?connectToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZWRpcmVjdCI6dHJ1ZSwicmVnaW9ucyI6WyJVUyIsIkNBIl0sImlzcyI6Im1lbGQuaW8iLCJjb25uZWN0aW9uIjoiV1E0NlhFVnpUMTR2cnJEcTZMU0pFZCIsImV4cCI6MTY4Njc5ODkzMywiaWF0IjoxNjg2Nzg0NTMzLCJhY2NvdW50IjoiVzlrYmtSbWU5VlQyaXo2cUFTZkFmMiIsImN1c3RvbWVyIjoiV1E0NlhEcllZTVlyZTlSQmt3YXl5USIsInByb2R1Y3RzIjpbIlRSQU5TQUNUSU9OUyIsIkJBTEFOQ0VTIiwiSURFTlRJRklFUlMiLCJPV05FUlMiXSwicm91dGluZ1Byb2ZpbGUiOiJXR3ZGWHRYYkRvQ2VXc3hVdHVpeFB5In0.jAwpUokwkSKi7BTwKJOY_Y6XAPv_O8yOi6mVaUKxnMI"
}
```
### Key response fields
| Field | Description |
| :------------------- | :-------------------------------------------------------------------------------------------------- |
| `id` | The Meld connection id. Use this to look up the connection later. |
| `connectToken` | The JWT used to launch the widget. Expires after 3 hours. |
| `customerId` | Meld's id for the customer. Persist this to track the customer across connections. |
| `externalCustomerId` | The id you passed in (if any), echoed back. |
| `widgetUrl` | The full URL with the token attached. You can load this directly in an iframe to launch the widget. |
## Common errors
| HTTP status | Likely cause | Developer action |
| :----------------- | :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ |
| `401 Unauthorized` | Missing or invalid `Authorization` header | Verify the API key value and the `BASIC ` prefix; confirm you are hitting the correct environment |
| `400 Bad Request` | Invalid product name, both required and optional product overlap, or unsupported region | Check `products` / `optionalProducts` / `regions` values against the API reference |
| `400 Bad Request` | No required product specified when using `optionalProducts` | Move at least one product into the `products` array |
| `404 Not Found` | The `institutionId` you passed does not exist | Re-resolve the institution via the `/institutions` endpoint |
| `5xx` | Transient Meld or provider issue | Retry with backoff; if it persists, contact Meld support |
Now that you have your connect token, you are ready to move on to [launching the widget](/docs/bank-linking/creating-connections/launch-the-widget).