API Keys and the REST API
Part of the MountDev Ops Workspace documentation. Updated November 17, 2026
MountDev Ops Workspace documentation | Updated November 17, 2026
Your other systems can read and change your workspace through its REST API, each with an API key of its own. A key works like a person with a role: it sees and changes exactly what its access allows, with the same checks as the screens, and everything it does is written in the Activity Log with its name.
API Keys
Select the Settings gear at the bottom of the menu, then Connections: the API Keys tab is first (owners and admins only; action core.api_keys.list). Searching for "API key", or for a key's name, opens it too:
- Make a Key (action
core.api_keys.create): a name (name it after the system that will use it), its access, and optionally the addresses it may be used from. The key is shown once, with Copy. Copy it then: it is never shown again, to anyone, because only a fingerprint of it is kept. - Access:
- Every record, like an admin: sees and changes every record in every app, as an admin does.
- By app role, like a member: a role in each app (Manager, Team member, Viewer, or one of your own roles), as a member has (Roles). Records a key adds are owned by the key, so a Team member key sees only the records it added. If a role it has is deleted later, the key keeps only the least access in that app until you choose another. No access keeps the key out of an app entirely: it sees none of that app's records, runs none of its actions, and the app's actions are left out of GET
actions. No access is where every app starts, so a new key has nothing until you choose a role, and an app you add later is No access for every key.
- Its address (optional): an email address of the key's own, so people can assign work to the system that uses the key, such as an assistant, by putting that address in a record's Assigned to or Project manager field. A member-level key then sees those records the way a member assigned to them does, and time it logs is under that address. Nobody in your workspace may have the address, and no other key; if someone joins with it later, the key stops using it, so a key never sees what a person sees. GET
meshows the address in use. - Kind: Reporting (the usual: records by role, and the reporting scopes below) or Billing (changes what you pay for through the Billing API, with the services it may add and an optional monthly limit; it can never read).
- Reporting scopes: what the key may read about your websites through the Reporting API, each read only:
sites:read,stats:read,reports:read,events:read,export:read,issues:read, andactivity:read. A key starts with none. Changing a key without choosing its scopes keeps the ones it has. - Allowed addresses: IP addresses or ranges, such as 203.0.113.7 or 203.0.113.0/24, one per line. A call from any other address is refused and logged. Empty means any address.
- Each key shows, in plain words, what it may reach in each app, such as "Projects: Manager | CRM: No access" (or "Every app: everything, like an admin"), with Edit right beside it to change that. It also shows the last 4 characters of the key, when it was last used and from where, and how many calls it has made.
- Edit (action
core.api_keys.update): its name, its role in each app, its scopes, and its addresses. The key itself stays the same. - Rotate (action
core.api_keys.rotate): a new key with the same name, access, and scopes, shown once with Copy. Choose how long the old key keeps working: not at all (it stops at once), or up to 24 hours so the system using it can switch over. The key's list shows when the old key stops. - Revoke (action
core.api_keys.revoke): the key is refused from its next call on, for good. Make a new key to replace it.
Make one key per system, so each can be revoked on its own. AI agents can never see or make API keys.
A key can also come from a pairing code: an outside app trades a one-time code for a key limited to one record. Such a key is listed here with the record it belongs to, can be rotated or revoked, and cannot be edited. It reads its own record, the records that link to it, and the record's history, and nothing else. See Pairing Codes.
What a Key Can Never Do
A key never reaches what stays with people: people, roles, and access; Settings (apps, modules, and fields); importing and exporting; billing settings; API connections, webhooks, automations, inbound webhooks, and other keys; and the Activity Log. It can never reply to a client by email or charge money. It can run only the actions marked safe for keys: the record actions below, and the app actions AI agents may use outside Settings.
Calling the API
The API's address is your workspace's address followed by /api/v1/, shown with Copy on the API Keys tab. Send the key in the Authorization header:
Authorization: Bearer mdo_...
Bodies are JSON. Every answer is JSON: { "result": ... } when it worked.
Errors
Every refusal has the same shape: { "error": "a plain reason", "code": "one_word" }. Show error to people; check code in your code.
| Status | code | What it means |
|---|---|---|
| 400 | bad_request | The request was not understood (the reason says what to change) |
| 401 | unauthorized | The key is missing, wrong, or revoked |
| 403 | forbidden | The key may not do that, or not from this address, or it lacks the scope |
| 404 | not_found | The address or record does not exist (a record or website the key may not see answers the same way) |
| 405 | method_not_allowed | That method is not used at this address |
| 409 | conflict | Someone changed the record since you read it |
| 413 | too_large | Too much at once (bodies up to 1 MB) |
| 429 | rate_limited | Too many requests: wait for Retry-After seconds |
| 500, 502, 503 | server_error, unavailable | Something went wrong on our side: try again shortly |
Limits
Each key may make 120 calls a minute (an export page of the Reporting API counts as 10), counted for that key alone. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (when the next minute starts, in seconds since 1970). Over the limit, a call is refused with 429 and Retry-After.
| Method and address | What it does |
|---|---|
GET me | The key's name, access, scopes, and address, your company's name, and the key's limits |
GET modules | Every module the key can see, with its fields |
GET records/<module> | Records of a module, newest change first. Optional q (text to find, a record number too), limit (up to 200), offset, sort (updated, created, number, or a field's key), and dir (asc or desc; updated and created are newest first unless dir is asc). Each record has its number when it has one |
POST records/<module> | Add a record: { "values": { "<field>": ... } } |
GET records/<module>/<id> | One record, its fields, and what the key may do with it |
PATCH records/<module>/<id> | Change some values: { "values": { ... }, "version": 3 }. With a version, nothing is saved if the record changed since |
DELETE records/<module>/<id> | Delete a record (when its access allows) |
GET records/<module>/<id>/history | The record's history |
GET search?q=<text> | Records matching the text in every module the key can see, up to 5 from each (limit up to 20) |
GET actions | Every action the key can run, with its inputs |
POST actions/<action> | Run one of those actions with its input as the body |
Your websites, their stats, monthly reports, website events, and an export of all of it are in the Reporting API, at addresses under sites, reports, events, and export.
A module is named by its app and key, such as crm.contacts, crm.deals, or helpdesk.tickets; GET modules lists them. Values are checked exactly as on the screens: a value that does not fit a field is refused with the reason, and nothing is saved.
A login field (see Login Fields) is read without its password. A key with edit access can save one with a password, and can get the password back only with POST actions/core.records.login.reveal, which is written in the Activity Log.
For example, to add a contact:
POST /api/v1/records/crm.contacts Authorization: Bearer mdo_... Content-Type: application/json
{ "values": { "name": "Ann Lee", "email": "ann@example.com" } }
Changes made with a key are marked API key in each record's history and in the Activity Log, and they set off your webhooks and automations like any other change.
