Skip to content

Get started with the REST API

The REST API lets your own code manage a Jump Desktop for Teams team, for example to sync computers with an asset database or archive connection history. To start, create an API token in the Teams dashboard, then call https://api.jumpdesktop.com with it.

Before you start

  • A Jump Desktop for Teams team.
  • The Admin or Admin (Read-Only) role on that team. Most team endpoints reject other roles. Admin (Read-Only) can only read. See Team roles.

Prefer the command line? Jump CLI (beta) wraps the same team operations in commands, uses the same API tokens, and outputs JSON with --json for scripts and tools to parse.

Create an API token

  1. Sign in to the Teams dashboard and click Security in the sidebar.
  2. In API Tokens, click Generate new token.
  3. Fill in the New API token dialog:
    • What's this token for?: a label, for example Inventory sync. Required.
    • Expiry: from 1 day to 6 months, a custom date, or Never (the default).
    • Issue read-only token: select this if your script only reads data.
  4. Click Generate Token.
  5. Copy the token. You can't see it again after you close the dialog.

The token acts as your account, with your role on each of your teams: a token created by an Admin can change anything that Admin can.

Read-only tokens can only make GET requests. POST, PUT, PATCH, and DELETE requests fail with 403, even for endpoints that only read or remove data.

Keep tokens in a secret store or environment variable, not in source code. To revoke a token, click the delete icon next to it in API Tokens, then click Delete in the confirmation dialog. Anything using it loses access immediately.

Authenticate

Send the token as a bearer token on every request:

Authorization: Bearer <token>

The examples on these pages read it from the JUMP_API_TOKEN environment variable:

export JUMP_API_TOKEN='paste-your-token-here'

Make your first call

GET /v1/user/teams returns the IDs of the teams you belong to. It works for any role and token.

curl --fail-with-body -sS https://api.jumpdesktop.com/v1/user/teams \
  -H "Authorization: Bearer $JUMP_API_TOKEN"

Uses the requests package.

import os

import requests

resp = requests.get(
    "https://api.jumpdesktop.com/v1/user/teams",
    headers={"Authorization": f"Bearer {os.environ['JUMP_API_TOKEN']}"},
)
if not resp.ok:
    raise SystemExit(f"{resp.status_code} {resp.text}")

print(resp.json())

Node.js 18 or later. Save as teams.mjs and run node teams.mjs.

const res = await fetch("https://api.jumpdesktop.com/v1/user/teams", {
  headers: { Authorization: `Bearer ${process.env.JUMP_API_TOKEN}` },
});

if (!res.ok) {
  console.error(res.status, await res.text());
  process.exit(1);
}

console.log(await res.json());

Invoke-RestMethod throws on a non-2xx response.

$headers = @{ Authorization = "Bearer $env:JUMP_API_TOKEN" }

try {
    Invoke-RestMethod -Uri "https://api.jumpdesktop.com/v1/user/teams" -Headers $headers
} catch {
    Write-Error "$($_.Exception.Response.StatusCode.value__) $($_.ErrorDetails.Message)"
    exit 1
}

Check that it worked

The response is a JSON array of team IDs:

["T-EXAMPLE123"]

A 401 means the token is missing, mistyped, expired, or revoked.

Find your team ID

Most endpoints take a team ID in the path, for example /v1/team/{teamID}/devices. Get it either way:

  • REST API: call GET /v1/user/teams. If you belong to several teams, call GET /v1/team/{teamID} for each ID and check name.
  • Teams dashboard: click your team's name in the sidebar. The team ID is the last part of the URL: https://app.jumpdesktop.com/dashboard/teams/T-EXAMPLE123.

Then list the team's computers with GET /v1/team/{teamID}/devices:

curl --fail-with-body -sS https://api.jumpdesktop.com/v1/team/T-EXAMPLE123/devices \
  -H "Authorization: Bearer $JUMP_API_TOKEN"

Handle errors

Failed requests return a non-2xx status and an errors array (the ApiErrors schema). Each error has status, and usually code; detail is included when there's more to say.

{"errors": [{"status": 403, "code": "forbidden"}]}
Status code Meaning
400 validation-error A request field is missing or invalid. detail names the field; its casing can differ from the JSON name.
401 unauthorized The token is missing, invalid, expired, or revoked, or you aren't an admin of the team in the path.
403 forbidden A read-only token, or an Admin (Read-Only) user, sent POST, PUT, PATCH, or DELETE.
429 rate-limited Too many requests from your IP address. Wait, then retry with backoff.

Other codes are endpoint-specific. Check status first, then code; don't match on detail text.

Next steps