Skip to main content
POST
/
api
/
v1
/
connections
/
link
Mint a hosted-link session
curl --request POST \
  --url https://breadbox.example.com/api/v1/connections/link \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "user_id": "<string>",
  "single_use": false,
  "redirect_url": "<string>",
  "label": "<string>",
  "expires_in_seconds": 1800
}
'
{
  "token": "<string>",
  "url": "<string>",
  "id": "<string>",
  "short_id": "<string>",
  "user_id": "<string>",
  "connection_id": "<string>",
  "single_use": true,
  "redirect_url": "<string>",
  "label": "<string>",
  "error_code": "<string>",
  "error_message": "<string>",
  "result_connection_ids": [
    "<string>"
  ],
  "expires_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.breadbox.sh/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-API-Key
string
header
required

Breadbox API key with format bb_<base62>. Carries either read_only or full_access scope. Write endpoints (and a handful of sensitive reads — /api-keys, /users/{user_id}/login) require full_access; endpoints that require it are flagged in their description.

Body

application/json
​
user_id
string
required

UUID or short_id of the household user the link is for.

​
provider
enum<string>

Optional. Empty / omitted lets the hosted page display a picker.

Available options:
,
plaid,
teller
​
single_use
boolean
default:false

When true, the session burns after the first successful link.

​
redirect_url
string

Optional URL the hosted page redirects to after completion.

​
label
string

Optional human-readable label for the agent's audit timeline.

​
expires_in_seconds
integer

TTL in seconds. 0 (or omitted) selects the default of 900 (15 minutes). Values above 3600 are rejected.

Required range: 0 <= x <= 3600

Response

Hosted-link session created.

A hosted-link session is the agent-facing record of a "share this URL with the user so they can connect a bank in their browser" flow. Returned by GET /connections/link/{id} and (extended with token and url) by POST /connections/link.

​
token
string
required

Plaintext bearer token. Returned exactly once at session creation; never echoed back by GET /connections/link/{id}.

​
url
string<uri>
required

Fully-qualified URL the end-user should open. Built from the request scheme + host + /link/<token>.

​
id
string
​
short_id
string
​
user_id
string
​
provider
enum<string>

"plaid", "teller", or empty string. Empty means the hosted page shows a picker so the user chooses a provider.

Available options:
,
plaid,
teller
​
action
enum<string>
Available options:
link,
relink
​
connection_id
string

Present only for action: "relink" — the connection being re-authenticated.

​
single_use
boolean
​
redirect_url
string

Optional URL the hosted page redirects to after completion.

​
label
string

Optional human-readable label shown in the agent's audit timeline.

​
status
enum<string>
Available options:
pending,
active,
completed,
failed,
expired,
consumed
​
error_code
string

Present only on status: "failed".

​
error_message
string

Present only on status: "failed".

​
result_connection_ids
string[]

UUIDs of the bank connections the user added during the session. Always present; empty array until at least one connection has been recorded.

​
expires_at
string<date-time>
​
started_at
string<date-time> | null

Stamped when the hosted page first transitions the session to active.

​
completed_at
string<date-time> | null

Stamped when the session reaches completed or failed.

​
created_at
string<date-time>