Skip to content

Get started with the REST API#

The REST API is an HTTPS interface for managing a Jump Desktop for Teams team from your own code, for example to synchronize computers with an asset database or archive connection history. To start, create an API token in the Teams dashboard, then send requests to https://api.jumpdesktop.com with that token.

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. The Admin (Read-Only) role has read-only access. See Team roles.

For command-line automation, Jump CLI Beta wraps the same team operations in commands and uses the same API tokens. Its --json option produces JSON output 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 option if your script only reads data.
  4. Click Generate Token.
  5. Copy the token. The token cannot be displayed again after you close the dialog.

An API token authenticates as your account and carries your role on each of your teams. A token created by an Admin can make any change that Admin can make.

Read-only tokens are restricted to GET requests. POST, PUT, PATCH, and DELETE requests fail with 403, including requests to endpoints that only read or remove data.

Store 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. Any script or tool using a revoked token loses access immediately.

Authenticate#

Send the API token as a bearer token in the Authorization header of every request:

Authorization: Bearer <token>

The examples in the REST API documentation read the token 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. This endpoint accepts any role and any 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 response indicates that the token is missing, mistyped, expired, or revoked.

Find your team ID#

Most endpoints require a team ID in the path, for example /v1/team/{teamID}/devices. To find the team ID, use either method:

  • REST API: call GET /v1/user/teams. If you belong to several teams, call GET /v1/team/{teamID} for each ID and compare 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#

A failed request returns a non-2xx status and an errors array (the ApiErrors schema). Each error includes status and usually code; detail is included when additional information is available.

{"errors": [{"status": 403, "code": "forbidden"}]}
Status code Meaning
400 validation-error A request field is missing or invalid. detail names the field; the casing of that name can differ from the JSON field name.
401 unauthorized The token is missing, invalid, expired, or revoked, or you are not 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 came from your IP address. Wait, then retry with backoff.

Other codes are endpoint-specific. Check status first, then code; do not match on detail text.

Next steps#