Link Sessions

Create and exchange link tokens to connect your users to their biller accounts via the Elements. A link token initializes the Connect flow, and after the user completes linking, you exchange the public token for a permanent access token.

Related guides: Link a Biller Account · Elements SDK

The Link Token object

A Link Token initializes a Connect session. It is short-lived, scoped to a single end user and set of consents, and passed to Elements on your frontend to start the link flow. Token strings are opaque and their prefixes differ by environment: sandbox returns sb_link_tok_… / sb_ltk_…, production returns lt_… and a UUID id. Never parse them — treat both as opaque strings.

Attributes

link_token*string	The link token used to initialize Elements
link_token_id*string	Unique identifier for the link token
client_id*string	Your client ID, resolved from the API key you authenticated with
client_user_id*string	Your unique identifier for the end user
consentsstring[]	Consent scopes recorded for this session, e.g. ["bills:read"]. Empty when the mint omitted them.
redirect_uristring	URL to redirect the user after linking completes
biller_idstring	Pre-select a specific biller for the Connect flow
created_atstring	ISO 8601 timestamp of when the token was created
expires_atstring	ISO 8601 timestamp of when the token expires

The Link Token object

{
  "link_token": "sb_link_tok_9f2c1ab47e5d40b8",
  "link_token_id": "sb_ltk_4d1e77a2c9b3",
  "client_id": "your_client_id",
  "client_user_id": "user_12345",
  "consents": ["bills:read"],
  "redirect_uri": "https://yourapp.com/callback",
  "biller_id": null,
  "created_at": "2026-04-06T12:00:00Z",
  "expires_at": "2026-04-06T12:30:00Z"
}

POST/v1/link-tokens

Create a link token to start a Connect session. The token is short-lived and should be passed to Elements on your frontend immediately after creation.

Request body

client_idstring	Optional. Resolved from your API key. Send it only to assert the client you expect — a mismatch is rejected with 403.
client_user_id*string	Your unique identifier for the end user
consentsstring[]	Optional. Consent scopes to record on the session; the canonical spelling across these docs is ["bills:read"]. Not enum-validated today.
redirect_uristring	URL to redirect the user after linking completes
biller_idstring	Pre-select a specific biller for the Connect flow

Sample uses your_client_id · sign in to auto-fill your sandbox key

curl -X POST https://sandbox.api.billerapi.com/v1/link-tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BILLERAPI_API_KEY" \
  -d '{
    "client_user_id": "user_12345",
    "consents": ["bills:read"],
    "redirect_uri": "https://yourapp.com/callback"
  }'

Response201 Created

{
  "success": true,
  "link_token": "sb_link_tok_9f2c1ab47e5d40b8",
  "link_token_id": "sb_ltk_4d1e77a2c9b3"
}

POST/v1/link-tokens/:public_token/exchange

Exchange the public token (received after a user completes the Connect flow) for a permanent access token. The access token is used to retrieve bills on behalf of the user.

Path parameters

public_token*string

The public token from the Elements callback

Sample uses your_client_id · sign in to auto-fill your sandbox key

curl -X POST https://sandbox.api.billerapi.com/v1/link-tokens/sb_public_tok_6b1f0c9d3a874e21/exchange \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BILLERAPI_API_KEY" \
  -d '{}'

Response200 OK

{
  "success": true,
  "access_token": "sb_access_tok_c7d4e91a2b6f8035",
  "biller_id": "sb_utility",
  "account_link_id": "link_abc123",
  "link_id": "link_abc123"
}

Was this page helpful?