Authentication

All ListBee API requests authenticate with an API key passed as a Bearer token. Keys start with lb_ and are tied to one account.

Authorization: Bearer lb_...

Missing or invalid keys return 401.

Two ways to get a key

1. Bootstrap API (agent-driven) — the agent creates an account, a human pastes a 6-digit OTP, the agent gets a key. No console visit required.
2. Console (human-driven) — sign in at console.listbee.so, create keys in the API Keys page.

Both paths produce the same account. If an account already exists for that email, bootstrap reuses it.

Bootstrap flow

Two API calls plus a poll. The agent drives; the human hands over one 6-digit code and completes Stripe Connect in a browser.

Step 1: Send OTP

1
from listbee import ListBee
2
3
client = ListBee()  # no api_key needed for bootstrap
4
start = client.bootstrap.start(email="seller@example.com")
5
# Tell the human: check your email for a 6-digit code.

Response:

1
{
2
  "object": "bootstrap_session",
3
  "bootstrap_token": "bst_abc123",
4
  "account_id": "acc_01J3K4M5N6P7Q8R9S0T1U2V3W4",
5
  "otp_expires_at": "2026-04-17T12:10:00Z"
6
}

The bootstrap_token is single-use and expires in 10 minutes. The account_id is stable — you can start polling it immediately.

Step 2: Verify and collect the key

The human reads the 6-digit code from their email and pastes it back. The agent submits it with the bootstrap_token.

1
result = client.bootstrap.verify(
2
    bootstrap_token=start.bootstrap_token,
3
    otp_code="123456",
4
)
5
api_key = result.api_key                        # lb_... — save immediately, not shown again
6
onboarding_url = result.stripe_onboarding_url   # hand to the human

Response:

1
{
2
  "object": "bootstrap_result",
3
  "account_id": "acc_01J3K4M5N6P7Q8R9S0T1U2V3W4",
4
  "api_key": "lb_01J3K4M5N6P7Q8R9S0T1U2V3W4X5Y6Z7",
5
  "stripe_onboarding_url": "https://connect.stripe.com/setup/s/...",
6
  "readiness": {
7
    "operational": false,
8
    "actions": [
9
      {
10
        "code": "stripe_connect_required",
11
        "kind": "human",
12
        "priority": "required",
13
        "message": "Complete Stripe Connect onboarding to accept payments.",
14
        "resolve": {"method": "redirect", "url": "https://connect.stripe.com/setup/s/..."}
15
      }
16
    ],
17
    "next": "stripe_connect_required"
18
  }
19
}

The API key is returned once. Listings can already be created and published — payment collection unlocks once Stripe Connect completes.

Step 3: Poll until Stripe is connected

Hand stripe_onboarding_url to the human. While they complete onboarding in a browser, the agent polls:

1
import time
2
3
while True:
4
    status = client.bootstrap.poll(result.account_id)
5
    if status.ready:
6
        break
7
    time.sleep(5)

ready: true means readiness.operational is true — the account can accept payments.

One-liner helper

The Python and TypeScript SDKs bundle the full flow in bootstrap.run():

1
api_key = client.bootstrap.run(
2
    "seller@example.com",
3
    on_otp=lambda: input("Enter OTP: "),
4
    on_human_action=lambda url: print(f"Visit: {url}"),
5
)

run() calls start, prompts for the OTP via on_otp, calls verify, hands the Stripe URL to on_human_action, and polls until the account is ready. It returns the API key.

Revoking a key

An agent can destroy its own key without a human in the loop — useful if the key is leaked or the host is compromised.

1
client.api_keys.self_revoke()
2
# The calling key is dead the moment this returns.

POST /v1/api-keys/self-revoke revokes the key used to authenticate the call. It cannot list, read, or touch any other key on the account. Multi-key management (list, create, revoke a different key) is console-only at console.listbee.so.

Threat model for the OTP-over-chat handoff

The bootstrap flow deliberately funnels the OTP code through the human’s chat with the agent: the agent reads it, and that’s required — it submits it to /verify. The code is short-TTL (10 min), single-use, and scoped to ListBee via the paired bootstrap_token. Agents should not persist or log the OTP after verify succeeds.

If this model doesn’t fit, the human can bootstrap through the console and hand the agent a key manually.

Related

• Quickstart — bootstrap to first listing in under 5 minutes
• Readiness — what the actions array tells your agent to do next