Skip to content
ReferenceForDeveloperVendor developer⏱ About 20 min
Before you start:
  • A product of type remote instance or set-up wizard

Provisioning API for vendor-hosted products ​

If your product runs on your own servers (a remote instance or a set-up wizard product), BMA handles the buying and billing and tells your system what to do: create an account when a customer buys, suspend it when they don't pay, switch it back on, and close it when they leave. You build a small HTTPS API that answers these calls.

Set up ​

  1. In your product's version, set the integration's provisioning_url (https), for example https://api.northwind.example.com/bma. BMA calls <provisioning_url>/<action>.
  2. In the vendor portal, open Provisioning and create your secret (prov_…, shown once). BMA signs every call with it, and you sign callbacks with it.
  3. Choose how customers sign in to your product: sso_mode (see Sign-in).
  4. Run the conformance check in Provisioning. A product of these types can't be approved without a passing run from the last 90 days.

The calls ​

CallWhenBody (JSON)
POST /createa customer bought it or started a free trialfulfillment_id, action, subscription_id, callback_url, marketplace {code, name}, customer {tenant_id, name, email} (plus host and host_org_id when bought in a host's marketplace), plan {id, name, model, cycle, seats}, parameters {…} (the customer's wizard answers)
POST /suspendunpaid for 14 days (usual setting), or BMA staff suspended itfulfillment_id, action, subscription_id, callback_url, instance_id
POST /unsuspendpaid, or staff switched it back onsame
POST /terminatecancelled, ended, or unpaid for 45 dayssame
POST /ssoa user clicks Open, or one of your screens in their BMA menu (only with sso_mode: vendor_sso)instance_id, subscription_id, user {id, name, email, tenant_admin}, and target (the screen's https address) when they opened a menu entry: answer with a url that lands there

GET /health, GET /status/<instance_id> and POST /change-plan are used by the conformance check. BMA doesn't send plan changes to live customers yet.

Every call carries ​

HeaderValue
BMA-Signaturet=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")> (a GET signs an empty body)
Idempotency-Keyful_…: the same on every retry of one call. Do the work once per key and answer the same way again.
BMA-FulfillmentBMA's id for this call
BMA-Api-Version1

Check the signature exactly like a webhook: reject a t more than 5 minutes off. Answer within 15 seconds (BMA's usual timeout).

Your answers ​

You answerBMA does
2xx with {"status":"done"} (for /create: plus "instance_id", at most 128 characters, and optionally an https "launch_url")marks it done; the customer is told the product is ready
202, or 2xx with {"status":"pending"}asks again with the same key after 15 minutes, then hourly; or finish sooner with the callback
2xx with {"status":"failed"}fails it at once
4xx (except 408, 425, 429)fails it at once
5xx, 408, 425, 429 or no answerretries after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h; fails after 8 attempts

A call that's still not done 72 hours after it started fails. When a create fails for good, the customer's subscription is cancelled and an unpaid first invoice is voided; BMA staff are told.

Finishing later: the callback ​

http
POST https://bma.botmodepro.com/mp/v1/provisioning/callback
BMA-Signature: t=<unix>,v1=<hex HMAC-SHA256(your secret, "<t>.<raw body>")>
Content-Type: application/json

{"fulfillment_id": 812, "status": "done", "instance_id": "nw-1042", "launch_url": "https://app.northwind.example.com/1042"}

status is done or failed (with an optional message). BMA answers {"ok": true, "status": "done"}; sending the same callback again changes nothing. A bad signature gets 401.

Report usage ​

For usage-based and tiered plans, send what each customer used. BMA bills it after the period ends.

http
POST /mp/v1/provisioning/usage
BMA-Signature: t=<unix time>,v1=<hex HMAC-SHA256 of "<t>.<body>" with your provisioning secret>
Content-Type: application/json

{"instance_id": "inst-4821", "quantity": 125, "idempotency_key": "evt-2026-11-15-4821-01"}
  • Name the subscription by instance_id (your instance) or subscription_id.
  • quantity is a positive whole number of units used since your last report.
  • idempotency_key (8–64 letters, digits or . _ : -) makes a report safe to resend: the second call returns the first record with "duplicate": true.
  • A wrong signature, or a subscription that isn't yours, answers 401 bad_signature. A plan that isn't usage-based answers 409 not_metered.
  • Only the marketplace team can correct usage downward.

Sign-in to your product ​

When a customer clicks Open, BMA checks the subscription is trialing, active or past due and set up, then:

sso_modeWhat happens
noneopens your launch_url (the one your create answer gave, or the product's)
vendor_ssoBMA calls your POST /sso and sends the user to the https url you answer with
jwtBMA opens launch_url?token=<JWT>: HS256, signed with your provisioning secret, valid 120 seconds, with iss: "bma", aud: <your vendor code>, sub, name, email, tenant_id, tenant_admin, instance_id, iat, exp, jti

Check the JWT's signature, aud, exp and that each jti is used once.

The conformance check ​

Run from Provisioning in the vendor portal against your real provisioning_url. It passes when none of these fail:

CheckExpects
healthGET /health answers
unsigneda call without a signature gets 401
bad signaturea wrongly signed call gets 401
createa create finishes with an instance_id (BMA follows 202s for up to 60 seconds)
replaythe same Idempotency-Key gives the same instance
statusGET /status/<id> shows it active
sso/sso answers an https url (only with sso_mode: vendor_sso)
suspend, then statusit shows suspended
unsuspend, then statusit shows active
change plan/change-plan succeeds
terminate, then statusit shows terminated

A pass is valid for 90 days, for the same server as your provisioning_url. Changing the URL, the launch URL or the sign-in mode sends the version back for BMA's review.

  • Webhooks (signature checking, same scheme)
  • Embed (customer.host and host_org_id tie an account to a host's customer)