RMM / PSA integration surface at https://<your-host>/api/v1/pub/v1/*.
All endpoints require an API key in the Authorization header:
Authorization: Bearer rk_<48-hex>
Keys are created under Settings → Monitoring & API → API keys
(/settings/api-keys, added in 0.29 — before that the screen did not exist
and keys could only be made with the admin API POST /api/v1/apikeys, which
still works). A Business Owner creates keys for their own business; a Platform
Admin picks the business. The raw key is shown once at creation;
server-side we store only a SHA-256 hash. Keys support:
- Business — Platform Admins only; a key always belongs to one business.
- A name you will recognise in the audit log.
- Scopes — tick only what the integration needs.
- Create key — the key is shown once, with a Copy button.
- Existing keys: prefix, scopes, last use, expiry, and Revoke.
- name — human label
- businessId — the business the key belongs to. Required. A key acts as a
Business Owner within that business and nowhere else; it is never a Platform
Admin. Keys created before v0.8.0 had no business and were revoked by migration
0009— re-issue them per business. - scopes — one or more of
companies:read,companies:write,users:read,users:write,computers:read,computers:write,sessions:read,enrollment:write,audit:read. Creating any key needs a fresh re-authentication (0.34; 0.33 asked only forenrollment:write): the API answers403 STEP_UP_REQUIRED(apikey.create), the console asks you to confirm it is you and sends the same request again, so the form is kept. A key is long-lived access that keeps working after you sign out, which is why every scope is gated, not only the one that enrols computers. Access is checked first: another business is a 403, an unknown one a 404, no valid scope a 400 — none of them prompts.API_KEY_CREATEDrecords the step-up method. - expiresInDays — optional TTL (1–3650), null = never expires
Revocation is immediate and never needs a step-up. Keys cannot be edited: there is no route that changes a key's scopes or restores a revoked key, so creating one is the only way to get a key's access. To change what a key may do, create a new key (which asks you to confirm it is you) and revoke the old one. Rate-limited to 300 req/min per key.
Every route enforces its declared scope; missing scopes → HTTP 401.
GET /pub/v1/whoami→{ businessId, apiKeyId, scopes, timestamp }
businesses is the current path; companies remains as an alias for integrations
built against v0.6/v0.7.
GET /pub/v1/businesses?search=…— scopecompanies:readReturns only the key's own business.GET /pub/v1/businesses/:id— scopecompanies:readAnother business's id returns 404.POST /pub/v1/businesses— scopecompanies:writeAlways 403. Creating a business is a platform-operator action and an API key is never a Platform Admin. Use the web UI.
GET /pub/v1/users— scopeusers:readThe people in the key's business.POST /pub/v1/users/invite— scopeusers:write{ "email": "john@acme.example", "firstName": "John", "lastName": "Smith", "level": "BUSINESS_USER", "capabilities": ["computers:view", "computers:connect"] }levelisBUSINESS_USERorBUSINESS_OWNER. Creating a Business Owner requires Platform Admin, so an API key gets 403 — it can only add Business Users. Omittingcapabilitiesapplies the defaults (computers:view,computers:connect). See access-control.md for the full capability vocabulary.
GET /pub/v1/computers?search=…&status=…&platform=…&page=1&limit=50— scopecomputers:readScoped to the key's business; there is no cross-business listing.GET /pub/v1/computers/:id— scopecomputers:readAnother business's id returns 404.
-
POST /pub/v1/enrollment/tokens— scopeenrollment:write. No step-up: an API key cannot do one. Instead, creating the key needs a fresh re-authentication in the console (0.33 forenrollment:write, 0.34 for every key), and every token a key mints is audited withmintedVia: "api-key"and the key's id. See sign-in.md.{ "accessMode": "ASSIGNED_USERS" | "COMPANY_WIDE", "assignedUserIds": ["usr_..."], "platform": "windows" | "linux" | "macos", "expiresInDays": 1, "description": "RMM deployment 2026-08-25" }The token is bound to the key's own business — there is no
businessIdto pass and no way to mint one for a different business. Every id inassignedUserIdsmust be an active member of that same business or the request is rejected.The machine that later redeems the token cannot influence which business it lands in or who gets access; both are stamped from the token at mint time. Returns:
{ "success": true, "data": { "id": "tok_...", "token": "raw-token-shown-once", "expiresAt": "…", "install": { "platform": "windows", "url": "https://.../api/v1/public/install/win/<token>", "command": "irm https://.../api/v1/public/install/win/<token> | iex" } } }Pass the
commandto your RMM script deployer or Intune Win32-app payload. -
GET /pub/v1/enrollment/tokens— scopeenrollment:write— list active tokens.
KEY='rk_...' # from Admin → API Keys
# Whoami
curl -s -H "Authorization: Bearer $KEY" \
https://remote.example/api/v1/pub/v1/whoami
# The key's own business
curl -s -H "Authorization: Bearer $KEY" \
https://remote.example/api/v1/pub/v1/businesses
# Mint a Windows install command for a specific user
curl -sX POST -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
https://remote.example/api/v1/pub/v1/enrollment/tokens \
-d '{"assignedUserIds":["usr_..."], "platform":"windows"}'Every response is wrapped in { "success": true, "data": ... }. What sits
under data is not uniform, and this trips integrators up:
| Route | data is |
|---|---|
GET /pub/v1/whoami |
no data wrapper — fields are at the top level |
GET /pub/v1/businesses |
an array of businesses |
GET /pub/v1/users |
an array of memberships |
GET /pub/v1/enrollment/tokens |
an array of tokens |
GET /pub/v1/computers |
an object: { endpoints, total, page, limit, pages } |
Only computers is paginated, and only it nests its array under a key. Treat
data.endpoints as the list there and data as the list everywhere else.
{
"success": true,
"businessId": "cmtaiwkcv000rza3semyybks5",
"apiKeyId": "cmtaj6l5g0007rjrpd756sliz",
"scopes": ["companies:read", "computers:read", "users:read", "enrollment:write"],
"timestamp": "2026-08-26T20:13:11.632Z"
}Note there is no data key here — read businessId and scopes directly. This
is the cheapest call for verifying a key works and discovering what it may do.
{
"success": true,
"data": [
{
"id": "cmtaiwkcv000rza3semyybks5",
"name": "Cascade Accounting",
"code": "CASC",
"email": "it@casc.example.com",
"city": "Seattle",
"state": "WA",
"country": "US",
"isActive": true,
"quickConnectEnabled": true,
"createdAt": "2026-08-26T20:05:12.079Z",
"_count": { "endpoints": 3, "sites": 0 }
}
]
}Always exactly one element — the key's own business. Use _count.endpoints for
a machine count instead of listing computers just to count them.
{
"success": true,
"data": {
"endpoints": [
{
"id": "cmtaiwkdb0017za3stnccaho1",
"name": "BACKOFFICE-01",
"hostname": "BACKOFFICE-01",
"status": "OFFLINE",
"platform": "Windows",
"osVersion": "Microsoft Windows NT 10.0.26100.0",
"ipAddress": "203.0.113.26",
"isOnline": false,
"isManaged": true,
"lastSeenAt": "2026-08-24T20:05:12.095Z",
"accessMode": "ASSIGNED_USERS",
"customerId": "cmtaiwkcv000rza3semyybks5",
"rustdeskNode": {
"rustdeskId": "145925926",
"lastSeenAt": "2026-08-24T20:05:12.095Z",
"hasPassword": true
},
"tags": [],
"aliases": []
}
],
"total": 3, "page": 1, "limit": 50, "pages": 1
}
}Two things worth knowing:
- The RustDesk ID is nested under
rustdeskNode, not on the endpoint. A machine that has not completed enrolment hasrustdeskNode: null. - The password is never returned.
hasPasswordtells you whether one is stored; the credential itself is not exposed through this API at all.
status is the administrative state (ACTIVE, OFFLINE, ARCHIVED,
PENDING_ENROLLMENT); isOnline is reachability — the agent heartbeat or a
live RustDesk registration. They can disagree — an ACTIVE machine that stopped
checking in, and that RustDesk cannot reach, is isOnline: false. From 0.35
connectivity says which kind of online: online (the agent checked in within
30 minutes), agent_silent (reachable through RustDesk, agent silent — remote
control works, nothing the agent reports is current) or offline.
data is an array of memberships, each wrapping the person under user:
{
"success": true,
"data": [
{
"id": "cmtaiwkcy000uza3saz93v5jm",
"userId": "cmtaiwkcw000sza3shgvnvoy9",
"customerId": "cmtaiwkcv000rza3semyybks5",
"isActive": true,
"capabilities": [],
"role": { "name": "Business Owner" },
"user": {
"id": "cmtaiwkcw000sza3shgvnvoy9",
"email": "owner@casc.example.com",
"firstName": "Dana",
"lastName": "Cascade",
"jobTitle": "IT Manager",
"status": "ACTIVE"
}
}
]
}An empty capabilities array means the role defaults apply, not that the person
has none.
Errors share one envelope:
{
"success": false,
"statusCode": 401,
"code": "UNAUTHORIZED",
"message": "Missing required scopes: companies:write",
"path": "/api/v1/pub/v1/companies",
"timestamp": "2026-08-26T20:13:11.836Z"
}| Situation | Status | message |
|---|---|---|
No or malformed Authorization header |
401 | Missing or malformed API key |
| Revoked, expired or unknown key | 401 | Missing or malformed API key |
| Key lacks the route's scope | 401 | Missing required scopes: <list> |
| Action needs Platform Admin | 403 | varies |
| Id belongs to another business | 404 | Not found |
| Over 300 req/min | 429 | rate limit |
A missing scope returns 401, not 403. Branch on message, or check
whoami first — retrying a 401 as if the key were invalid will not help.
Verified against a live instance; only ids and hostnames are anonymised.
KEY='rk_...'
HOST='https://remote.example'
# 1. Confirm the key works and see what it may do.
curl -s -H "Authorization: Bearer $KEY" "$HOST/api/v1/pub/v1/whoami"
# 2. Page through the computers. Only this route paginates.
page=1
while :; do
body=$(curl -s -H "Authorization: Bearer $KEY" \
"$HOST/api/v1/pub/v1/computers?page=$page&limit=50")
echo "$body" | jq -r '.data.endpoints[]
| [.name, .rustdeskNode.rustdeskId // "not-enrolled", .isOnline, .lastSeenAt]
| @tsv'
pages=$(echo "$body" | jq -r '.data.pages')
[ "$page" -ge "$pages" ] && break
page=$((page + 1))
done
# 3. Mint a Windows install command for a new machine.
curl -sX POST -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
"$HOST/api/v1/pub/v1/enrollment/tokens" \
-d '{"platform":"windows","accessMode":"COMPANY_WIDE","expiresInDays":1,
"description":"RMM rollout"}' \
| jq -r '.data.install.command'Step 3 prints a one-liner to hand to your deployment tool. The token is single-use and carries the business and access rules with it, so the machine running it cannot choose which business it joins.
Polling guidance: lastSeenAt only moves every 3 minutes (the agent heartbeat),
so polling faster than that gains nothing and will hit the 300 req/min limit on
any fleet of size.
- Every request is confined to the key's business by the same
AccessControlServicescope rule that governs interactive sessions — there is no separate code path for API keys. - Enrollment tokens are single-use and expire in 24h by default. The endpoint that redeems the token cannot influence which company / user gets access — those are stamped on the token at mint time.
- Bearer tokens must be transmitted over HTTPS. Keys are hashed at rest (SHA-256); the raw value is only returned to the caller at creation.
- Rate limit: 300 req/min/key.
- All key issuance and revocation is audited (
API_KEY_CREATED,API_KEY_REVOKED).
apps/api/scripts/e2e-public-api.mjs walks the full API-key flow (mint → whoami
→ list → create → mint enrollment → scope-enforcement → revoke → verify
revocation blocks). Run with DATABASE_URL=... node apps/api/scripts/e2e-public-api.mjs.
