Skip to content

Automation API

Jump to bottom
Marc Pope edited this page Oct 8, 2026 · 4 revisions

Automation API

A REST API for scripting the console: users, devices, groups, address books and audit logs. Authenticated with scoped bearer tokens, separate from console sessions.

Base path: /api/v1

Tokens

Settings → Security → API tokens. Give the token a name, an optional expiry date, and a permission level per area — the same matrix used by roles: None, View (r) or Manage (rw), over devices, users, groups, address books, logs, strategies, settings and tokens.

Three things to know:

  • The token is shown once. Only a SHA-256 hash and a short prefix are stored, so it genuinely cannot be recovered afterwards — not by an administrator, not from the database. Copy it at creation.
  • Tokens are create-only. There is no edit screen. To change a token's permissions, issue a new one and retire the old.
  • A token can never exceed its creator. Permissions are clamped to what the issuing user already holds, so token creation is not an escalation path.

Tokens can also be deactivated, which takes effect immediately.

Making a request

curl -s -H "Authorization: Bearer cdk_your_token_here" \
     https://console.example.com/api/v1/devices

Every response uses the same envelope:

{ "code": 0, "data": [], "message": "" }

code is 0 on success and non-zero on error, and the HTTP status matches:

Status Meaning
401 Missing or invalid token
403 Token lacks the required permission
404 Not found
422 Validation failed
429 Rate limited

A permission failure tells you exactly what was missing:

{ "code": 403, "data": null, "message": "Token lacks 'rw' permission on 'device'." }

Pagination

List endpoints add total, current and total_pages.

  • ?page= — page number
  • ?page_size= — default 50, maximum 200

Rate limit

The API is limited to 120 requests per minute per token. Batch work should page rather than hammer.

Endpoints

Grouped by the permission area that governs them.

Area Endpoints
user /users, /users/{id}, /users/{id}/enable, /users/{id}/disable, /users/{id}/force-logout
device /devices, /devices/{id}, /devices/{id}/enable, /devices/{id}/disable, /devices/{id}/assign
group /user-groups, /user-groups/{id}/members, /device-groups, /device-groups/{id}/members
address_book /address-books, /address-books/{id}/peers, /address-books/{id}/tags, /address-books/{id}/rules
audit /audits/conn, /audits/file, /audits/alarm, /audits/console — read-only

Reads need r on the area; writes need rw.

Device payloads

Device objects carry the full hardware and presence inventory (extended in 1.1.0 with cpu, memory, note, status, last_online_ip and the timestamps, and in 1.8.0 with registered_ip):

{
  "id": 7,
  "rustdesk_id": "118452907",
  "uuid": "…",
  "alias": "Reception",
  "hostname": "HO-RECEPTION",
  "os": "Windows 11 Pro",
  "platform": "windows",
  "cpu": "AMD Ryzen 7 5800X, 8 cores",
  "memory": "32 GB",
  "version": "1.4.2",
  "username": "reception",
  "note": null,
  "status": "active",
  "online": true,
  "last_online_at": "2026-08-06T14:00:00+00:00",
  "last_online_ip": "198.51.100.226",
  "registered_ip": "198.51.100.226",
  "created_at": "2026-07-20T09:12:00+00:00",
  "updated_at": "2026-08-06T14:00:00+00:00",
  "user": { "id": 6, "username": "dana" },
  "device_group": { "id": 1, "name": "Head Office" },
  "disabled": false,
  "possible_duplicates": []
}

possible_duplicates (since 1.12.0) lists the IDs of devices that look like the same machine under another ID, the same pairs the Devices screen flags. It is empty when there are none or the pair was marked not a duplicate.

status is active, pending (held at the approval gate) or disabled (recycle bin). Fields are only ever added, never renamed or removed, so it is safe to build against them.

The Devices screen's Export CSV offers the same inventory as a spreadsheet for one-off pulls.

Deleting a device

DELETE /devices/{id} deletes the device permanently. Unlike the console, it does not go through the recycle bin.

Since 1.10.0 it takes remove_from_address_books=true, which also removes the device's entries from every address book. The token then needs address_book: rw as well, or the call gets 403. The response data is {"address_book_entries_removed": N}. Left out, or false, address books are not touched.

Audit payloads

New fields are appended; existing ones keep their names.

  • Connections (/audits/conn), since 1.10.0: note, note_by (the console username, null for a note typed with the in-session Note button) and noted_at. See session notes.
  • File transfers (/audits/file), since 1.11.0: files, the file names and sizes the client listed as [{"name": ..., "size": ...}] (up to the 10 largest; empty for a single-file job, whose path is the file), and clipboard, true for files copied through the clipboard, which have an empty path.

Unattended deployment with --assign

The RustDesk client's --assign flag lets an installer register a device against the console and place it correctly on first run, with no console work afterwards. It can set the device's owner, its device group and its strategy.

The token used by --assign needs:

  • device: rw — always
  • strategy: rw — additionally, if you pass --strategy_name

Tokens created before 0.9.0 will not assign strategies. Assigning a strategy began requiring strategy: rw on top of device: rw in that release. A token without it gets 403 Token lacks 'rw' permission on 'strategy', and an unknown strategy name now returns 404 instead of being silently ignored. Since tokens cannot be edited, issue a replacement with the strategy permission. In practice nothing can have depended on the old behaviour — --strategy_name was previously accepted and did nothing.

Related

Clone this wiki locally