Appearance
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
- In your product's version, set the integration's
provisioning_url(https), for examplehttps://api.northwind.example.com/bma. BMA calls<provisioning_url>/<action>. - 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. - Choose how customers sign in to your product:
sso_mode(see Sign-in). - 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
| Call | When | Body (JSON) |
|---|---|---|
POST /create | a customer bought it or started a free trial | fulfillment_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 /suspend | unpaid for 14 days (usual setting), or BMA staff suspended it | fulfillment_id, action, subscription_id, callback_url, instance_id |
POST /unsuspend | paid, or staff switched it back on | same |
POST /terminate | cancelled, ended, or unpaid for 45 days | same |
POST /sso | a 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
| Header | Value |
|---|---|
BMA-Signature | t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")> (a GET signs an empty body) |
Idempotency-Key | ful_…: the same on every retry of one call. Do the work once per key and answer the same way again. |
BMA-Fulfillment | BMA's id for this call |
BMA-Api-Version | 1 |
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 answer | BMA 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 answer | retries 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) orsubscription_id. quantityis 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 answers409 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_mode | What happens |
|---|---|
none | opens your launch_url (the one your create answer gave, or the product's) |
vendor_sso | BMA calls your POST /sso and sends the user to the https url you answer with |
jwt | BMA 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:
| Check | Expects |
|---|---|
| health | GET /health answers |
| unsigned | a call without a signature gets 401 |
| bad signature | a wrongly signed call gets 401 |
| create | a create finishes with an instance_id (BMA follows 202s for up to 60 seconds) |
| replay | the same Idempotency-Key gives the same instance |
| status | GET /status/<id> shows it active |
| sso | /sso answers an https url (only with sso_mode: vendor_sso) |
| suspend, then status | it shows suspended |
| unsuspend, then status | it shows active |
| change plan | /change-plan succeeds |
| terminate, then status | it 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.