TBBN Developers

post/v1/auth/merchant/otp/request

Request email OTP for merchant rep login

curl -X POST https://api.tbbnetwork.com/v1/auth/merchant/otp/request \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com"
}'

Request body

Field	Type	Required
email	string (email)	yes

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/auth/merchant/otp/verify

Verify merchant rep OTP and issue a session

curl -X POST https://api.tbbnetwork.com/v1/auth/merchant/otp/verify \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "email",
  "code": "code",
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}'

Request body

Field	Type	Required
email	string	yes
code	string	yes
merchantId	string (uuid)	—

Response (200)

Field	Type	Required
accessToken	string	—
refreshToken	string	—
merchantId	string (uuid)	—
role	string	—

Example 200 response

{
  "accessToken": "accessToken",
  "refreshToken": "refreshToken",
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "role": "role"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/auth/merchant/switch

Move a merchant session to another Merchant the person is on

curl -X POST https://api.tbbnetwork.com/v1/auth/merchant/switch \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "refreshToken",
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}'

Request body

Field	Type	Required
refreshToken	string	yes
merchantId	string (uuid)	yes

Response (200)

Field	Type	Required
accessToken	string	—
refreshToken	string	—
merchantId	string (uuid)	—
role	string	—

Example 200 response

{
  "accessToken": "accessToken",
  "refreshToken": "refreshToken",
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "role": "role"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/auth/merchant/access

Open a Merchant from your TBBN sign-in

curl -X POST https://api.tbbnetwork.com/v1/auth/merchant/access \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}'

Request body

Field	Type	Required
merchantId	string (uuid)	—

Response (200)

Field	Type	Required
accessToken	string	—
merchantId	string (uuid)	—
role	string	—

Example 200 response

{
  "accessToken": "accessToken",
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "role": "role"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

get/v1/auth/account/workplaces

The Businesses and Merchants you own or work for

curl -X GET https://api.tbbnetwork.com/v1/auth/account/workplaces \
  -H "Authorization: Bearer <session access token>" \

Response (200)

Field	Type	Required
businesses	object[]	—
merchants	object[]	—
pendingInvitations	integer	—

Example 200 response

{
  "businesses": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Acme Co.",
      "logoUrl": null,
      "role": "role",
      "hostsSpaces": false
    }
  ],
  "merchants": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Acme Co.",
      "logoUrl": null,
      "role": "role",
      "status": "status"
    }
  ],
  "pendingInvitations": 1
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/auth/member/register

Direct self-registration for a Marketplace profile — the primary way anyone joins TBBN now.

curl -X POST https://api.tbbnetwork.com/v1/auth/member/register \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Co.",
  "email": "you@example.com",
  "phone": "+1-555-0173",
  "country": "US"
}'

Request body

Field	Type	Required
name	string	yes
email	string (email)	—
phone	string	—
country	string	—

Possible errors

409	An account with this email or phone already exists

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/auth/member/otp/verify

Complete self-registration and issue a session

curl -X POST https://api.tbbnetwork.com/v1/auth/member/otp/verify \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "target",
  "code": "code"
}'

Request body

Field	Type	Required
target	string	yes
code	string	yes

Response (200)

Field	Type	Required
accessToken	string	—
refreshToken	string	—

Example 200 response

{
  "accessToken": "accessToken",
  "refreshToken": "refreshToken"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/auth/seller/otp/request

Request OTP for a marketplace member's direct TBBN Marketplace login

curl -X POST https://api.tbbnetwork.com/v1/auth/seller/otp/request \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com"
}'

Request body

Field	Type	Required
email	string (email)	yes

Possible errors

404	No marketplace account found for this email

post/v1/auth/seller/otp/verify

Verify marketplace member OTP and issue a session

curl -X POST https://api.tbbnetwork.com/v1/auth/seller/otp/verify \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "email",
  "code": "code"
}'

Request body

Field	Type	Required
email	string	yes
code	string	yes

Response (200)

Field	Type	Required
accessToken	string	—
refreshToken	string	—

Example 200 response

{
  "accessToken": "accessToken",
  "refreshToken": "refreshToken"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/auth/seller/magic-link/request

Request a passwordless magic link for a marketplace member

curl -X POST https://api.tbbnetwork.com/v1/auth/seller/magic-link/request \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com"
}'

Request body

Field	Type	Required
email	string (email)	yes

get/v1/auth/seller/magic-link/consume

Consume a magic link token, issuing a session

curl -X GET https://api.tbbnetwork.com/v1/auth/seller/magic-link/consume \
  -H "Authorization: Bearer sk_sandbox_..." \

Parameters

token

query

required

Response (200)

Field	Type	Required
accessToken	string	—
refreshToken	string	—

Example 200 response

{
  "accessToken": "accessToken",
  "refreshToken": "refreshToken"
}

post/v1/auth/refresh

Rotate a refresh token for a new access token

curl -X POST https://api.tbbnetwork.com/v1/auth/refresh \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "refreshToken"
}'

Request body

Field	Type	Required
refreshToken	string	yes

Response (200)

Field	Type	Required
accessToken	string	—
refreshToken	string	—

Example 200 response

{
  "accessToken": "accessToken",
  "refreshToken": "refreshToken"
}

Possible errors

401	Refresh token invalid, expired, or reused (triggers session-chain revocation)

post/v1/auth/logout

Revoke the current session

curl -X POST https://api.tbbnetwork.com/v1/auth/logout \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \

get/v1/auth/me

Who the credential belongs to. With an API key: the Merchant it's for and whether it's a test key (livemode false) — a quick way to check a key works. With a sign-in token: the signed-in account.

curl -X GET https://api.tbbnetwork.com/v1/auth/me \
  -H "Authorization: Bearer sk_sandbox_..." \

Response (200)

Field	Type	Required
principalType	merchant_api_key \| space_api_key \| merchant_rep \| marketplace_member	—
userId	string (uuid)	—
merchantId	string,null (uuid)	—
merchant	objectnull	—
businessId	string,null (uuid)	—
livemode	boolean	—
restriction	WIND_DOWN \|	—
sellerId	string,null (uuid)	—
role	stringnull	—

Example 200 response

{
  "principalType": "merchant_api_key",
  "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "merchant": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "displayName": "Acme Co.",
    "status": "status",
    "livemode": false
  },
  "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "livemode": false,
  "restriction": "WIND_DOWN",
  "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "role": null
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/auth/step-up/request

Send a fresh verification code to the signed-in caller's own account email. Sensitive actions (account deletion, editing an already-verified Business, Merchant or Space) need this code confirmed first, on top of the session.

curl -X POST https://api.tbbnetwork.com/v1/auth/step-up/request \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/auth/step-up/confirm

Verify the step-up code and receive a short-lived (5 minute), single-action token. Pass it back as X-TBBN-Step-Up-Token on the one request it was scoped for — a step-up token is never a substitute for that route's own principal/role check, only an added re-authentication layer on top of it.

curl -X POST https://api.tbbnetwork.com/v1/auth/step-up/confirm \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "code",
  "scope": "scope"
}'

Request body

Field	Type	Required
code	string	yes
scope	string	yes

Response (200)

Field	Type	Required
token	string	—

Example 200 response

{
  "token": "tok_5f2f8b91a3c4"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

get/v1/auth/account/export

Download everything TBBN holds about the signed-in member, as JSON

curl -X GET https://api.tbbnetwork.com/v1/auth/account/export \
  -H "Authorization: Bearer <session access token>" \

Response (200)

Field	Type	Required
exportedAt	string (date-time)	—
guide	object[]	—

Example 200 response

{
  "exportedAt": "2026-07-01T12:00:00Z",
  "guide": [
    {
      "key": "key",
      "holds": "holds",
      "onDelete": "ERASE",
      "why": "why"
    }
  ]
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/auth/account/delete

Delete the signed-in member's account

curl -X POST https://api.tbbnetwork.com/v1/auth/account/delete \
  -H "Authorization: Bearer <session access token>" \
  -H "X-TBBN-Step-Up-Token: <step-up-token>" \
  -H "Idempotency-Key: 5f2f...b91" \

Parameters

X-TBBN-Step-Up-Token

header

required

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

put/v1/auth/account/avatar

Set the signed-in member's profile photo

curl -X PUT https://api.tbbnetwork.com/v1/auth/account/avatar \
  -H "Authorization: Bearer <session access token>" \
  -H "Content-Type: application/json" \
  -d '{
  "avatarUrl": "https://example.com/resource"
}'

Request body

Field	Type	Required
avatarUrl	string (uri)	yes

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

delete/v1/auth/account/avatar

Remove the signed-in member's profile photo

curl -X DELETE https://api.tbbnetwork.com/v1/auth/account/avatar \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

put/v1/auth/account/location

Save the signed-in member's approximate location

curl -X PUT https://api.tbbnetwork.com/v1/auth/account/location \
  -H "Authorization: Bearer <session access token>" \
  -H "Content-Type: application/json" \
  -d '{
  "latitude": 1,
  "longitude": 1
}'

Request body

Field	Type	Required
latitude	number	yes
longitude	number	yes

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

delete/v1/auth/account/location

Clear the signed-in member's saved location

curl -X DELETE https://api.tbbnetwork.com/v1/auth/account/location \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

get/v1/auth/account/work-email/providers

Which school or work account sign-ins can verify an email (google, microsoft).

curl -X GET https://api.tbbnetwork.com/v1/auth/account/work-email/providers \
  -H "Authorization: Bearer <session access token>" \

Response (200)

Field	Type	Required
providers	string[]	—

Example 200 response

{
  "providers": [
    "google"
  ]
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/auth/account/work-email/start

Starts verifying a school or work email by signing in to that account. Send the member to url; they come back to tbbnetwork.com/account/work-email with code and state.

curl -X POST https://api.tbbnetwork.com/v1/auth/account/work-email/start \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "google"
}'

Request body

Field	Type	Required
provider	google \| microsoft	yes

Response (200)

Field	Type	Required
url	string (uri)	—

Example 200 response

{
  "url": "https://example.com/resource"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/auth/account/work-email/finish

Finishes the sign-in as the same member who started it and adds the address to their account as verified. Only an address whose domain the organization owns is accepted.

curl -X POST https://api.tbbnetwork.com/v1/auth/account/work-email/finish \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "code",
  "state": "state"
}'

Request body

Field	Type	Required
code	string	yes
state	string	yes

Response (200)

Field	Type	Required
email	string (email)	—

Example 200 response

{
  "email": "you@example.com"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}