Skip to content
How-toForDeveloper⏱ About 30 min
Before you start:
  • Your marketplace code and host code from BMA staff
  • The SSO secret (shown once to BMA staff)
  • A page on one of your embed origins

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 ​

ValueExampleNotes
BMA addresshttps://bma.botmodepro.com
Marketplace codelakeside
Host codelakeside
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 charactersShown once. Keep it on your server only. Use the string as is as the HMAC key.
Embed originshttps://*.lakeside.example.com, https://lakeside.example.comOnly 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 ​

  1. 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>
  2. Add an endpoint on your server that returns a token for the signed-in user (see The token). Never sign tokens in the browser.

  3. 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>
  4. Decide who may buy and who may manage with the mp_roles claim (see Roles).

  5. 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.

ClaimRequiredMeaning
issyesyour host code, e.g. lakeside
audyesbma-marketplace:<marketplace code>, e.g. bma-marketplace:lakeside
subyesthe user's id in your system (1–128 characters)
jtiyesa unique id per token (8–64 characters of A–Z a–z 0–9 . _ : -); each token is accepted once
iat, expyesUnix seconds; exp at most 300 seconds after iat, and in the future
email, namenoshown as "Signed in as …"
org_id, org_nameto buythe customer organization the user acts for, e.g. the dealership. Buying, billing and everything bought belong to it.
mp_rolesno["buyer"], ["host_admin"] or ["host_viewer"], or a combination (see below)
mp_host_rolenowith 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_rolesThe person can
nonebrowse, read reviews, ask a vendor for a quote, open the products their organization already has
buyeralso 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_adminopen 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_vieweropen Manage read-only

This is the Manage tab's Requests page, where a manager decides on vendors' listing requests:

  1. 1Approve the request: the product goes live in your marketplace and the vendor is told.
  2. 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.

Directiontypedata
frame → your pagemp:readycode
frame → your pagemp:resizeheight (px)
frame → your pagemp:navigatepath (#/, #/p/<slug>, #/c/<category> or #/a/<partner>)
frame → your pagemp:sessionsigned_in, name or error
your page → framemp:tokentoken (sent by embed.js from getToken)
your page → framemp:navigatepath
your page → framemp:thememode: 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.

RequestAnswer
GET infoname, 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 methe 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:

reasonIt meansDo this
formatnot a three-part JWTsend the token string only, no quotes or Bearer
algnot HS256sign with HMAC-SHA256
signaturethe signature doesn't matchuse the SSO secret exactly as given; check it wasn't rotated
isswrong issueriss must be your host code
audwrong audienceaud must be bma-marketplace:<marketplace code>
timesiat/exp out of rangeexp at most 300 s after iat; check your server clock
expiredexp has passedmake a new token for each sign-in
submissing or too longsend your user id as a string, 1–128 characters
jtimissing or badly formed8–64 characters of A–Z a–z 0–9 . _ : -
replayedthis jti was used beforemake a new token each time; never cache tokens
You seeIt meansDo this
The frame stays blank; the browser console mentions frame-ancestorsthe page isn't on an embed originask BMA staff to add the origin
"Not found" for a draft marketplacethe session isn't from your hostsign in with a token from your host, or ask staff to activate the marketplace
Pay does nothingthe browser blocked the pop-upallow pop-ups for your page