Authentication

Merchant API keys

Authorization: Bearer sk_live_... for production, sk_sandbox_... for sandbox — the prefix determines the environment, not the host you call. Generate a key from your Merchant Dashboard; you'll see the full value exactly once, so store it like any other secret. Keys are scoped and independently revocable — rotating one doesn't affect any human session on the same account.

Seller sign-in (for embedded widgets or your own UI)

Sellers never have a password. Sign-in is a one-time code sent by email, or optionally phone, or a magic link — issued by TBBN, not something you implement yourself if you're using an official widget or SDK flow. If you're building a fully custom experience against the raw API: the code is 6 digits, expires in 10 minutes, and is capped at 5 send-requests per hour per address — build your UI to handle that rate limit gracefully (a clear "too many attempts, try again in a bit" state) rather than retrying silently.

Acting on behalf of a seller

Any route that mutates one seller's state (accept/reject/cancel an offer, cancel a trade session, confirm a peer-to-peer exchange) needs to know which seller you're acting for. There are exactly two valid ways:

• The seller themself, authenticated with their own session — they can only ever act for themselves.
• A merchant the seller is linked to — the core integration case, where your platform drives the flow through the API on behalf of your own seller. This is also the only way to act for a headless seller (one with no linked TBBN account at all).

An actingSellerId field on a request body is a statement of intent, not a grant of identity — it still has to match one of the two cases above. Naming a seller you don't actually have a relationship to gets rejected, not honored.

Rate limits

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. See API conventions for how these interact with usage metering on your plan.