Mint a hosted-link session

Creates a hosted-link session and returns the URL an end-user should open in their browser to add a new bank connection. The response carries a one-time-only bearer token and a fully-qualified url (scheme + host + /link/<token>). The token is never echoed back by GET /connections/link/{id} — capture it from this response and keep the URL alongside it.

• provider is optional. Empty means the hosted page presents a picker.
• expires_in_seconds is clamped to [0, 3600]. 0 (or missing) selects the default of 900s (15 minutes).
• Action is always link on this endpoint. Relink (re-authenticating an existing connection) is exposed separately via POST /connections/{id}/relink.

Requires full_access scope.

Mint a hosted-link session

cURL

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
}
'

import requests

url = "https://breadbox.example.com/api/v1/connections/link"

payload = {
    "user_id": "<string>",
    "single_use": False,
    "redirect_url": "<string>",
    "label": "<string>",
    "expires_in_seconds": 1800
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    user_id: '<string>',
    single_use: false,
    redirect_url: '<string>',
    label: '<string>',
    expires_in_seconds: 1800
  })
};

fetch('https://breadbox.example.com/api/v1/connections/link', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://breadbox.example.com/api/v1/connections/link",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'user_id' => '<string>',
    'single_use' => false,
    'redirect_url' => '<string>',
    'label' => '<string>',
    'expires_in_seconds' => 1800
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://breadbox.example.com/api/v1/connections/link"

	payload := strings.NewReader("{\n  \"user_id\": \"<string>\",\n  \"single_use\": false,\n  \"redirect_url\": \"<string>\",\n  \"label\": \"<string>\",\n  \"expires_in_seconds\": 1800\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://breadbox.example.com/api/v1/connections/link")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_id\": \"<string>\",\n  \"single_use\": false,\n  \"redirect_url\": \"<string>\",\n  \"label\": \"<string>\",\n  \"expires_in_seconds\": 1800\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://breadbox.example.com/api/v1/connections/link")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_id\": \"<string>\",\n  \"single_use\": false,\n  \"redirect_url\": \"<string>\",\n  \"label\": \"<string>\",\n  \"expires_in_seconds\": 1800\n}"

response = http.request(request)
puts response.read_body

201

{
  "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"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

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

201

application/json

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>