---
title: "Request Plaid Link token"
method: POST
path: "/plaid/link-tokens"
tags: ["External Accounts"]
---

# Request Plaid Link token

`POST /plaid/link-tokens`

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

## Request body

- PlaidLinkTokenRequest
  - `customerId` string, required — The ID of the customer for whom to create the Plaid Link token and external account

## Response `200`

Link token created successfully

- PlaidLinkTokenResponse
  - `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.
  - `expiration` string, date-time, required — The ISO 8601 timestamp when this link token expires. Link tokens typically expire after 4 hours.
  - `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.
  - `requestId` string — A unique identifier for this request, useful for debugging

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized
- `404` — Customer not found
- `500` — Internal service error

## Changes

- **2026-02-13** `ecd31fe01b4e` — 20 breaking, 4 warning
  - added `#/components/schemas/Error400_INVALID_INPUT, #/components/schemas/Error400_MISSING_MANDATORY_USER_INFO, #/components/schemas/Error400_INVITATION_ALREADY_CLAIMED, #/components/schemas/Error400_INVITATIONS_NOT_CONFIGURED, #/components/schemas/Error400_INVALID_UMA_ADDRESS, #/components/schemas/Error400_INVITATION_CANCELLED, #/components/schemas/Error400_QUOTE_REQUEST_FAILED, #/components/schemas/Error400_INVALID_PAYREQ_RESPONSE, #/components/schemas/Error400_INVALID_RECEIVER, #/components/schemas/Error400_PARSE_PAYREQ_RESPONSE_ERROR, #/components/schemas/Error400_CERT_CHAIN_INVALID, #/components/schemas/Error400_CERT_CHAIN_EXPIRED, #/components/schemas/Error400_INVALID_PUBKEY_FORMAT, #/components/schemas/Error400_MISSING_REQUIRED_UMA_PARAMETERS, #/components/schemas/Error400_SENDER_NOT_ACCEPTED, #/components/schemas/Error400_AMOUNT_OUT_OF_RANGE, #/components/schemas/Error400_INVALID_CURRENCY, #/components/schemas/Error400_INVALID_TIMESTAMP, #/components/schemas/Error400_INVALID_NONCE, #/components/schemas/Error400_INVALID_REQUEST_FORMAT, #/components/schemas/Error400_INVALID_BANK_ACCOUNT, #/components/schemas/Error400_SELF_PAYMENT, #/components/schemas/Error400_LOOKUP_REQUEST_FAILED, #/components/schemas/Error400_PARSE_LNURLP_RESPONSE_ERROR, #/components/schemas/Error400_INVALID_AMOUNT, #/components/schemas/Error400_WEBHOOK_ENDPOINT_NOT_SET, #/components/schemas/Error400_WEBHOOK_DELIVERY_ERROR` to the response body `oneOf` list for the response status `400`
  - added `#/components/schemas/Error401_UNAUTHORIZED, #/components/schemas/Error401_INVALID_SIGNATURE` to the response body `oneOf` list for the response status `401`
  - added `#/components/schemas/Error404_TRANSACTION_NOT_FOUND, #/components/schemas/Error404_INVITATION_NOT_FOUND, #/components/schemas/Error404_USER_NOT_FOUND, #/components/schemas/Error404_QUOTE_NOT_FOUND, #/components/schemas/Error404_LOOKUP_REQUEST_NOT_FOUND, #/components/schemas/Error404_TOKEN_NOT_FOUND, #/components/schemas/Error404_BULK_UPLOAD_JOB_NOT_FOUND, #/components/schemas/Error404_REFERENCE_NOT_FOUND` to the response body `oneOf` list for the response status `404`
  - added `#/components/schemas/Error500_GRID_SWITCH_ERROR, #/components/schemas/Error500_INTERNAL_ERROR` to the response body `oneOf` list for the response status `500`
  - …20 more
- …earlier changes not shown

[Full history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/plaid/link-tokens/post.md)

---

[API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/revisions/ecd31fe01b4e/schema)