Request Plaid Link token

Creates a Plaid Link token that can be used to initialize Plaid Link in your application. The Link token is used to authenticate the customer and allow them to select their bank account.

Async Flow:

1. Platform calls this endpoint to get a link_token and callbackUrl
2. Platform displays Plaid Link UI to the end customer using the link_token
3. End customer authenticates with their bank and selects an account
4. Plaid returns a public_token to the platform
5. Platform POSTs the public_token to the callbackUrl
6. Lightspark exchanges the public_token with Plaid and creates the external account asynchronously
7. Platform receives a webhook notification when the external account is ready

POST /plaid/link-tokens

JavaScript

JavaScript

import LightsparkGrid from '@lightsparkdev/grid';

const client = new LightsparkGrid({
  username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted
  password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted
});

const response = await client.plaid.createLinkToken({
  customerId: 'Customer:019542f5-b3e7-1d02-0000-000000000001',
});

console.log(response.callbackUrl);

200

{
  "linkToken": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",
  "expiration": "2025-10-05T18:30:00Z",
  "callbackUrl": "https://api.lightspark.com/grid/2025-10-13/plaid/callback/{plaid_link_token}",
  "requestId": "req_abc123def456"
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Body

application/json

customerId · string · required

The ID of the customer for whom to create the Plaid Link token and external account

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

Response

200

application/json

Link token created successfully

linkToken · string · required

The Plaid Link token to be used to initialize Plaid Link in your application. This token is single-use and expires after the specified expiration time.

Example:

"link-sandbox-af1a0311-da53-4636-b754-dd15cc058176"

expiration · string<date-time> · required

The ISO 8601 timestamp when this link token expires. Link tokens typically expire after 4 hours.

Example:

"2025-10-05T18:30:00Z"

callbackUrl · string · required

The URL where the platform should POST the public_token after the customer completes Plaid Link authentication. This will trigger asynchronous external account creation. The URL includes the linkToken as the path parameter.

Example:

"https://api.lightspark.com/grid/2025-10-13/plaid/callback/{plaid_link_token}"

requestId · string

A unique identifier for this request, useful for debugging

Example:

"req_abc123def456"