Skip to content
ReferenceForDeveloper⏱ About 8 min
Before you start:
  • Build access in the organization

Tenant API ​

The Tenant API gives an outside system a key for one organization and a set of named routes, each mapped to a named query, a builder table or an HTTP endpoint. It's set up in App Builder → Tenant API.

https://<your BMA>/api/index.php/tenant-api/v1/<organization code>/<route code>

Keys ​

  1. Tenant API: enter a Key name, pick Scopes, click Create API key.
  2. "Copy this key now — it will not be shown again". Keys look like tak_ and 48 letters and digits; BMA keeps only a hash and the prefix.
  3. Revoke a key in the list when it's no longer needed or may have leaked.
ScopeAllows
Run queries (query:run)routes that run a named query, including table-write queries
Read tables (table:read)routes that list a builder table
HTTP proxy (http:proxy)routes that call an outside endpoint

Give a key only the scopes it needs. Treat a query:run key as able to write if any route runs a write query.

Routes ​

New route: Route code, Title, HTTP method, and the Handler:

HandlerAnswers with
Named querythe query's result; the request's values fill {{input.x}}
Table list{"ok": true, "rows": [...], "total": N}; q searches, sort and dir order; at most the route's limit (50 by default, 200 at most), no paging
HTTP proxythe upstream's answer (public addresses only)

For GET, the query string is the input; otherwise the JSON body.

A request ​

bash
curl -H "X-Tenant-Api-Key: tak_…" \
  "https://<your BMA>/api/index.php/tenant-api/v1/<organization code>/open_checkouts?q=drill"

Authorization: Bearer tak_… works too. No session or CSRF token is needed.

json
{
  "success": true,
  "message": "",
  "data": { "ok": true, "rows": [ { "id": 3, "item": "Drill", "borrower": "Sam" } ], "total": 1 }
}

Errors ​

StatusMeans
401"Invalid or missing API key"
403"API key does not match tenant", or scope_required: the key lacks the route's scope (required_scope says which)
429"Too many failed attempts: try again later" (this address sent 30 wrong keys in five minutes) or "Rate limit: 120 calls a minute per key"; wait Retry-After seconds
404"Route not found" (code or method)
422the query or the route's settings are wrong
502the HTTP proxy's upstream failed

Limits: each key may make 120 calls a minute; after that the answer is 429 with Retry-After (seconds) and {"code": "rate_limited", "retry_after": N}. Wrong or missing keys count against the caller's address: after 30 in five minutes, every call from that address gets 429 until the window passes. Keep keys on servers, never in a browser or app.