Appearance
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
- Tenant API: enter a Key name, pick Scopes, click Create API key.
- "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. - Revoke a key in the list when it's no longer needed or may have leaked.
| Scope | Allows |
|---|---|
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:
| Handler | Answers with |
|---|---|
| Named query | the 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 proxy | the 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
| Status | Means |
|---|---|
| 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) |
| 422 | the query or the route's settings are wrong |
| 502 | the 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.