API keys
What it's for
API keys let your own systems — a CRM, an ERP, a website or a script — read a project's stages, zones and inventory and update units without anyone uploading a CSV. A typical use: when the CRM records a booking, it marks the plot Booked here, and every map changes colour.
Before you start
- You need to be a company owner or have the Company settings permission.
- Your company and the project must be active; requests for a suspended company or project are refused.
- Know which project the integration needs. Each key works for exactly one project; a project can have up to 20 keys.
- For unit lookups by your own IDs, fill the External ID (CRM / ERP) on units (form, CSV
external_id or the API).
Create a key
- Open Integrations → API access in the sidebar.
- Press Create API key.
- Enter a Key name that says what uses it (for example "CRM sync").
- Choose the Project.
- Tick the Permissions it needs (table below). Give the fewest that work.
- Press Create key. The dialog Copy your API key shows the full key once. Copy it into your system's secret store now; afterwards only its prefix is shown.
Permissions
| Permission | Allows |
| Read project | GET /project — the key's project details |
| Read stages & zones | GET /stages, GET /zones |
| Read inventory | GET /inventory (paginated, up to 100 per page, with search and status or stage filters) and GET /inventory/{id} |
| Update inventory | PATCH /inventory/{id} — stage, status, prices, areas, notes, internal sales fields, zones, section, external ID and more. Includes Read inventory. |
Call the API
- Base address: your app's address followed by
/api/v1, over HTTPS.
- Send the key in a header:
Authorization: Bearer mbk_live_…
- The project comes from the key; it is not part of the address.
- Find a unit by its ID, by
?lookup=external_id, or by ?lookup=unit_number (add &unique_identifier=… when numbers repeat).
- For a PATCH, send only the fields you want to change, as JSON.
- Answers come as
{ "data": … }; errors as { "message": … } with status 401 (bad or revoked key), 403 (missing permission), 404 (unit not found), 422 (invalid data) or 429 (too many requests).
The full reference with copyable examples is linked from the API access page (API documentation), available to every signed-in user.
Monitor and revoke
- The keys table shows each key's name, project, prefix, permissions, Last used and Status (Active or Revoked).
- Recent API activity lists requests with time, method and path, response status and duration — not the data sent.
- To stop a key, revoke it and confirm Revoke API key?. It stops working immediately and cannot be re-enabled.
What happens automatically
- Changes made through the API relink map shapes and recolour maps like any other inventory change, and appear in the unit's history.
- Creating and revoking keys is recorded in the security audit log.
- Each key may make 120 requests a minute by default; more get status 429 — wait and retry.
Tips and common questions
- Never put a key in website code, emails, chat or source control. Anyone with the key can access the linked project.
- To rotate a key, create a new one, switch your system to it, then revoke the old one.
- Use one key per system so you can revoke one without breaking the others.
- For a map on your website, use the embed rather than the API. See Share links & embed.
Related: Inventory basics · Inventory stages & colours · Team members & permissions