Skip to content

Automation API

Jump to bottom
Marc Pope edited this page Jul 26, 2026 · 1 revision

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.

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