Appearance
Embed a marketplace in your product
For a hostHost A company that shows a BMA marketplace inside its own software, for its own customers. A host can approve listings, vet vendors, sell ads and read reports. that shows its BMA marketplace inside its own web app. Your users browse, buy and manage what they've bought without leaving your product, and without a BMA login: your server vouches for them with a signed token.
What you get from BMA staff
| Value | Example | Notes |
|---|---|---|
| BMA address | https://bma.botmodepro.com | |
| Marketplace code | lakeside | |
| Host code | lakeside | |
| SSO secretSSO secret The shared secret a host uses to sign the sign-in tokens for its embedded marketplace. Shown once when BMA staff create it. | 43 characters | Shown once. Keep it on your server only. Use the string as is as the HMAC key. |
| Embed origins | https://*.lakeside.example.com, https://lakeside.example.com | Only pages on these origins can show the marketplace. |
BMA sends Content-Security-Policy: frame-ancestors with your embed origins, so browsers block the marketplace on any other site. https://*.example.com covers every subdomain but not https://example.com itself, so list both if you need both.
How sign-in works
The token travels from your page to the BMA frame by postMessage, never in a URL.
Steps
Show the marketplace without sign-in (works once the marketplace is active):
html<div id="bma-marketplace"></div> <script src="https://bma.botmodepro.com/mp/embed.js" data-marketplace="lakeside" data-target="#bma-marketplace" async></script>Add an endpoint on your server that returns a token for the signed-in user (see The token). Never sign tokens in the browser.
Mount the marketplace with that endpoint:
html<div id="bma-marketplace"></div> <script src="https://bma.botmodepro.com/mp/embed.js"></script> <script> const mp = BMAMarketplace.mount({ marketplace: 'lakeside', target: '#bma-marketplace', // Return a fresh token from YOUR server. getToken: () => fetch('/api/bma-marketplace-token', { credentials: 'include' }).then((r) => r.text()), onEvent: (type, data) => console.log(type, data), // mp:ready, mp:session, mp:navigate, mp:resize, mp:error }) // mp.navigate('#/p/some-product'); mp.setTheme('dark'); mp.destroy(); </script>Decide who may buy and who may manage with the
mp_rolesclaim (see Roles).Test on a draft marketplace. A draft is visible only to BMA staff and to sessions signed by its own host, so you can try everything before it goes live.
The frame resizes itself to its content. Pass autoHeight: false to turn that off; minHeight defaults to 480.
The token
A JWT signed with HS256 using the SSO secret. Any other algorithm is refused.
| Claim | Required | Meaning |
|---|---|---|
iss | yes | your host code, e.g. lakeside |
aud | yes | bma-marketplace:<marketplace code>, e.g. bma-marketplace:lakeside |
sub | yes | the user's id in your system (1–128 characters) |
jti | yes | a unique id per token (8–64 characters of A–Z a–z 0–9 . _ : -); each token is accepted once |
iat, exp | yes | Unix seconds; exp at most 300 seconds after iat, and in the future |
email, name | no | shown as "Signed in as …" |
org_id, org_name | to buy | the customer organization the user acts for, e.g. the dealership. Buying, billing and everything bought belong to it. |
mp_roles | no | ["buyer"], ["host_admin"] or ["host_viewer"], or a combination (see below) |
mp_host_role | no | with host_admin: "viewer" makes the Manage tab read-only (default: manager) |
js
import crypto from 'node:crypto'
const b64url = (buf) => Buffer.from(buf).toString('base64url')
export function bmaMarketplaceToken(user) {
const now = Math.floor(Date.now() / 1000)
const header = b64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }))
const claims = b64url(JSON.stringify({
iss: 'lakeside', aud: 'bma-marketplace:lakeside',
sub: String(user.id), jti: crypto.randomUUID(), iat: now, exp: now + 120,
email: user.email, name: user.name, org_id: String(user.dealerId), org_name: user.dealerName,
// only the people you trust to spend money for the dealership may buy
...(user.isDealerAdmin ? { mp_roles: ['buyer'] } : {}),
}))
const sig = crypto.createHmac('sha256', process.env.BMA_MARKETPLACE_SSO_SECRET)
.update(`${header}.${claims}`).digest('base64url')
return `${header}.${claims}.${sig}`
}php
function bma_marketplace_token(array $user, string $secret): string {
$b64 = fn ($s) => rtrim(strtr(base64_encode($s), '+/', '-_'), '=');
$now = time();
$h = $b64(json_encode(['alg' => 'HS256', 'typ' => 'JWT']));
$c = $b64(json_encode([
'iss' => 'lakeside', 'aud' => 'bma-marketplace:lakeside', 'sub' => (string) $user['id'],
'jti' => bin2hex(random_bytes(16)), 'iat' => $now, 'exp' => $now + 120,
'email' => $user['email'], 'name' => $user['name'],
'org_id' => (string) $user['dealer_id'], 'org_name' => $user['dealer_name'],
] + (!empty($user['is_dealer_admin']) ? ['mp_roles' => ['buyer']] : [])));
return "$h.$c." . $b64(hash_hmac('sha256', "$h.$c", $secret, true));
}python
import base64, hashlib, hmac, json, os, secrets, time
def _b64(b: bytes) -> str:
return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
def bma_marketplace_token(user: dict) -> str:
now = int(time.time())
header = _b64(json.dumps({"alg": "HS256", "typ": "JWT"}).encode())
claims = {
"iss": "lakeside", "aud": "bma-marketplace:lakeside", "sub": str(user["id"]),
"jti": secrets.token_hex(16), "iat": now, "exp": now + 120,
"email": user["email"], "name": user["name"],
"org_id": str(user["dealer_id"]), "org_name": user["dealer_name"],
}
if user.get("is_dealer_admin"):
claims["mp_roles"] = ["buyer"]
body = _b64(json.dumps(claims).encode())
sig = hmac.new(os.environ["BMA_MARKETPLACE_SSO_SECRET"].encode(), f"{header}.{body}".encode(), hashlib.sha256).digest()
return f"{header}.{body}.{_b64(sig)}"Roles
You decide who can do what. BMA trusts the roles in your signed token and keeps no copy of your users. A role lasts for the session (two hours); a new token carries the current roles.
mp_roles | The person can |
|---|---|
| none | browse, read reviews, ask a vendor for a quote, open the products their organization already has |
buyer | also buy for org_id (with a coupon if they have one), see Billing (subscriptions, invoice PDFs, billing contact, cards and bank accounts on file), cancel or resume subscriptions, and write the organization's review |
host_admin | open the Manage tab: approve, reject or hide listings (if your marketplace uses host approval), feature listings with dates, sort them, manage categories and collections, vet vendors and answer listing requests, change the marketplace's name and look, price ad placements and review ads, moderate reviews, read sales, ad and payout reports |
host_admin with mp_host_role: "viewer", or host_viewer | open Manage read-only |
This is the Manage tab's Requests page, where a manager decides on vendors' listing requests:
- 1Approve the request: the product goes live in your marketplace and the vendor is told.
- 2Reject it: the vendor is told, with your note.
org_id is optional for host_admin and host_viewer. A Manage session never has owner rights: the host's users, its API key and its webhooks need a BMA login linked to your host.
Who bills your customers
The first time BMA sees an org_id, it makes a BMA organization for it (no users; nobody can sign in to it). Your customers are billed by whoever sells the plan, which depends on how BMA staff set up your marketplace: BMA, your own company, or the vendor. They pay by card or bank account through Stripe, or by invoice. If you share in BMA's commission, your share shows in your host reports.
What's sold in a host marketplace
BMA modules install into BMA organizations, so they aren't listed in a host marketplace. Vendor-hosted products, set-up wizards, onboarding, quote requests and links are. When your customer buys a vendor-hosted product, the vendor's create call carries customer.host (your host code) and customer.host_org_id (your org_id), so the vendor can link the account to your customer.
Light and dark theme
By default the marketplace is light and shows a light / auto / dark switch (auto follows the visitor's device). To match your app instead, pass theme: 'light' or theme: 'dark' to mount() (or data-theme="dark" on the script tag), and call mp.setTheme('dark' | 'light' | 'auto') when your user switches. While you set the theme, the marketplace hides its own switch. Dark-mode logos and colours come from the marketplace branding.
Payments open in a new tab
Stripe's payment page can't run inside a frame. Pay and Add a card open it in a new tab, so allow pop-ups for the page that embeds the marketplace. The tab ends on a "you can close this tab" page, and the marketplace refreshes when the user comes back to your app.
Messages between your page and the frame
The frame posts only to a parent whose origin is an embed origin, and accepts messages only from it. embed.js checks that messages come from the BMA origin.
| Direction | type | data |
|---|---|---|
| frame → your page | mp:ready | code |
| frame → your page | mp:resize | height (px) |
| frame → your page | mp:navigate | path (#/, #/p/<slug>, #/c/<category> or #/a/<partner>) |
| frame → your page | mp:session | signed_in, name or error |
| your page → frame | mp:token | token (sent by embed.js from getToken) |
| your page → frame | mp:navigate | path |
| your page → frame | mp:theme | mode: light, dark or auto (sent by setTheme) |
Public read API
Everything under https://bma.botmodepro.com/mp/v1/<code>/. Send X-MP-Session with a session token where you have one.
| Request | Answer |
|---|---|
GET info | name, operator_name (who runs the marketplace: your name on your own marketplace), branding, currency, locale, terms URL, categories |
GET catalog?q=&category=&type= | listed products: slug, type, vendor, listing card, plans with list prices |
GET products/<slug> | one product with its full listing |
POST session {"token": "<jwt>"} | session, expires_at, user |
GET me | the session's user, or 401 |
A marketplace the caller may not see answers 404. Prices include the marketplace's markup.
If something goes wrong
When a token is refused, onEvent('mp:session', { signed_in: false, error }) fires. The answer of POST /mp/v1/<code>/session carries data.reason:
reason | It means | Do this |
|---|---|---|
format | not a three-part JWT | send the token string only, no quotes or Bearer |
alg | not HS256 | sign with HMAC-SHA256 |
signature | the signature doesn't match | use the SSO secret exactly as given; check it wasn't rotated |
iss | wrong issuer | iss must be your host code |
aud | wrong audience | aud must be bma-marketplace:<marketplace code> |
times | iat/exp out of range | exp at most 300 s after iat; check your server clock |
expired | exp has passed | make a new token for each sign-in |
sub | missing or too long | send your user id as a string, 1–128 characters |
jti | missing or badly formed | 8–64 characters of A–Z a–z 0–9 . _ : - |
replayed | this jti was used before | make a new token each time; never cache tokens |
| You see | It means | Do this |
|---|---|---|
The frame stays blank; the browser console mentions frame-ancestors | the page isn't on an embed origin | ask BMA staff to add the origin |
| "Not found" for a draft marketplace | the session isn't from your host | sign in with a token from your host, or ask staff to activate the marketplace |
| Pay does nothing | the browser blocked the pop-up | allow pop-ups for your page |