JumpCloud API (1.0)

Download OpenAPI specification:Download

Overview

JumpCloud's V1 API. This set of endpoints allows JumpCloud customers to manage commands, systems, and system users.

API Best Practices

Read the linked Help Article below for guidance on retrying failed requests to JumpCloud's REST API, as well as best practices for structuring subsequent retry requests. Customizing retry mechanisms based on these recommendations will increase the reliability and dependability of your API calls.

Covered topics include:

  1. Important Considerations
  2. Supported HTTP Request Methods
  3. Response codes
  4. API Key rotation
  5. Paginating
  6. Error handling
  7. Retry rates

JumpCloud Help Center - API Best Practices

API Key

Access Your API Key

To locate your API Key:

  1. Log into the JumpCloud Admin Console.
  2. Go to the username drop down located in the top-right of the Console.
  3. Retrieve your API key from API Settings.

API Key Considerations

This API key is associated to the currently logged in administrator. Other admins will have different API keys.

WARNING Please keep this API key secret, as it grants full access to any data accessible via your JumpCloud console account.

You can also reset your API key in the same location in the JumpCloud Admin Console.

Recycling or Resetting Your API Key

In order to revoke access with the current API key, simply reset your API key. This will render all calls using the previous API key inaccessible.

Your API key will be passed in as a header with the header name "x-api-key".

curl -H "x-api-key: [YOUR_API_KEY_HERE]" "https://console.jumpcloud.com/api/systemusers"

Introduction

JumpCloud System Context Authorization is an alternative way to authenticate with a subset of JumpCloud's REST APIs. Using this method, a system can manage its information and resource associations, allowing modern auto provisioning environments to scale as needed.

Notes:

  • The following documentation applies to Linux Operating Systems only.
  • Systems that have been automatically enrolled using Apple's Device Enrollment Program (DEP) or systems enrolled using the User Portal install are not eligible to use the System Context API to prevent unauthorized access to system groups and resources. If a script that utilizes the System Context API is invoked on a system enrolled in this way, it will display an error.

Supported Endpoints

JumpCloud System Context Authorization can be used in conjunction with Systems endpoints found in the V1 API and certain System Group endpoints found in the v2 API.

  • A system may fetch, alter, and delete metadata about itself, including manipulating a system's Group and Systemuser associations,
    • /api/systems/{system_id} | GET PUT
  • A system may delete itself from your JumpCloud organization
    • /api/systems/{system_id} | DELETE
  • A system may fetch its direct resource associations under v2 (Groups)
    • /api/v2/systems/{system_id}/memberof | GET
    • /api/v2/systems/{system_id}/associations | GET
    • /api/v2/systems/{system_id}/users | GET
  • A system may alter its direct resource associations under v2 (Groups)
    • /api/v2/systems/{system_id}/associations | POST
  • A system may alter its System Group associations
    • /api/v2/systemgroups/{group_id}/members | POST
      • NOTE If a system attempts to alter the system group membership of a different system the request will be rejected

Response Codes

If endpoints other than those described above are called using the System Context API, the server will return a 401 response.

Authentication

To allow for secure access to our APIs, you must authenticate each API request. JumpCloud System Context Authorization uses HTTP Signatures to authenticate API requests. The HTTP Signatures sent with each request are similar to the signatures used by the Amazon Web Services REST API. To help with the request-signing process, we have provided an example bash script. This example API request simply requests the entire system record. You must be root, or have permissions to access the contents of the /opt/jc directory to generate a signature.

Here is a breakdown of the example script with explanations.

First, the script extracts the systemKey from the JSON formatted /opt/jc/jcagent.conf file.

#!/bin/bash
conf="`cat /opt/jc/jcagent.conf`"
regex="systemKey\":\"(\w+)\""

if [[ $conf =~ $regex ]] ; then
  systemKey="${BASH_REMATCH[1]}"
fi

Then, the script retrieves the current date in the correct format.

now=`date -u "+%a, %d %h %Y %H:%M:%S GMT"`;

Next, we build a signing string to demonstrate the expected signature format. The signed string must consist of the request-line and the date header, separated by a newline character.

signstr="GET /api/systems/${systemKey} HTTP/1.1\ndate: ${now}"

The next step is to calculate and apply the signature. This is a two-step process:

  1. Create a signature from the signing string using the JumpCloud Agent private key: printf "$signstr" | openssl dgst -sha256 -sign /opt/jc/client.key
  2. Then Base64-encode the signature string and trim off the newline characters: | openssl enc -e -a | tr -d '\n'

The combined steps above result in:

signature=`printf "$signstr" | openssl dgst -sha256 -sign /opt/jc/client.key | openssl enc -e -a | tr -d '\n'` ;

Finally, we make sure the API call sending the signature has the same Authorization and Date header values, HTTP method, and URL that were used in the signing string.

curl -iq \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Date: ${now}" \
  -H "Authorization: Signature keyId=\"system/${systemKey}\",headers=\"request-line date\",algorithm=\"rsa-sha256\",signature=\"${signature}\"" \
  --url https://console.jumpcloud.com/api/systems/${systemKey}

Input Data

All PUT and POST methods should use the HTTP Content-Type header with a value of 'application/json'. PUT methods are used for updating a record. POST methods are used to create a record.

The following example demonstrates how to update the displayName of the system.

signstr="PUT /api/systems/${systemKey} HTTP/1.1\ndate: ${now}"
signature=`printf "$signstr" | openssl dgst -sha256 -sign /opt/jc/client.key | openssl enc -e -a | tr -d '\n'` ;

curl -iq \
  -d "{\"displayName\" : \"updated-system-name-1\"}" \
  -X "PUT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Date: ${now}" \
  -H "Authorization: Signature keyId=\"system/${systemKey}\",headers=\"request-line date\",algorithm=\"rsa-sha256\",signature=\"${signature}\"" \
  --url https://console.jumpcloud.com/api/systems/${systemKey}

Output Data

All results will be formatted as JSON.

Here is an abbreviated example of response output:

{
  "_id": "625ee96f52e144993e000015",
  "agentServer": "lappy386",
  "agentVersion": "0.9.42",
  "arch": "x86_64",
  "displayName": "ubuntu-1204",
  "firstContact": "2013-10-16T19:30:55.611Z",
  "hostname": "ubuntu-1204"
  ...

Additional Examples

Signing Authentication Example

This example demonstrates how to make an authenticated request to fetch the JumpCloud record for this system.

SigningExample.sh

Shutdown Hook

This example demonstrates how to make an authenticated request on system shutdown. Using an init.d script registered at run level 0, you can call the System Context API as the system is shutting down.

Instance-shutdown-initd is an example of an init.d script that only runs at system shutdown.

After customizing the instance-shutdown-initd script, you should install it on the system(s) running the JumpCloud agent.

  1. Copy the modified instance-shutdown-initd to /etc/init.d/instance-shutdown.
  2. On Ubuntu systems, run update-rc.d instance-shutdown defaults. On RedHat/CentOS systems, run chkconfig --add instance-shutdown.

Multi-Tenant Portal Headers

Multi-Tenant Organization API Headers are available for JumpCloud Admins to use when making API requests from Organizations that have multiple managed organizations.

The x-org-id is a required header for all multi-tenant admins when making API requests to JumpCloud. This header will define to which organization you would like to make the request.

NOTE Single Tenant Admins do not need to provide this header when making an API request.

Header Value

x-org-id

API Response Codes

  • 400 Malformed ID.
  • 400 x-org-id and Organization path ID do not match.
  • 401 ID not included for multi-tenant admin
  • 403 ID included on unsupported route.
  • 404 Organization ID Not Found.
curl -X GET https://console.jumpcloud.com/api/v2/directories \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-org-id: {ORG_ID}'

To Obtain an Individual Organization ID via the UI

As a prerequisite, your Primary Organization will need to be setup for Multi-Tenancy. This provides access to the Multi-Tenant Organization Admin Portal.

  1. Log into JumpCloud Admin Console. If you are a multi-tenant Admin, you will automatically be routed to the Multi-Tenant Admin Portal.
  2. From the Multi-Tenant Portal's primary navigation bar, select the Organization you'd like to access.
  3. You will automatically be routed to that Organization's Admin Console.
  4. Go to Settings in the sub-tenant's primary navigation.
  5. You can obtain your Organization ID below your Organization's Contact Information on the Settings page.

To Obtain All Organization IDs via the API

  • You can make an API request to this endpoint using the API key of your Primary Organization. https://console.jumpcloud.com/api/organizations/ This will return all your managed organizations.
curl -X GET \
  https://console.jumpcloud.com/api/organizations/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'

SDKs

You can find language specific SDKs that can help you kickstart your Integration with JumpCloud in the following GitHub repositories:

Application Templates

List Application Templates

The endpoint returns all the SSO / SAML Application Templates.

Sample Request

curl -X GET https://console.jumpcloud.com/api/application-templates \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["applicationtemplates","applicationtemplates.readonly"]
Authorizations:
x-api-key
query Parameters
fields
string

The space separated fields included in the returned records. If omitted the default list of fields will be returned.

limit
integer

The number of records to return at once.

skip
integer

The offset into the records to return.

sort
string

The space separated fields used to sort the collection. Default sort is ascending, prefix with - to sort descending.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/application-templates?fields=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE&skip=SOME_INTEGER_VALUE&sort=SOME_STRING_VALUE&filter=SOME_STRING_VALUE' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Get an Application Template

The endpoint returns a specific SSO / SAML Application Template.

Sample Request

curl -X GET https://console.jumpcloud.com/api/application-templates/{id} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["applicationtemplates","applicationtemplates.readonly"]
Authorizations:
x-api-key
path Parameters
id
required
string
query Parameters
fields
string

The space separated fields included in the returned records. If omitted the default list of fields will be returned.

limit
integer

The number of records to return at once.

skip
integer

The offset into the records to return.

sort
string

The space separated fields used to sort the collection. Default sort is ascending, prefix with - to sort descending.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/application-templates/{id}?fields=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE&skip=SOME_INTEGER_VALUE&sort=SOME_STRING_VALUE&filter=SOME_STRING_VALUE' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "_id": "string",
  • "active": true,
  • "beta": true,
  • "color": "",
  • "config": {
    },
  • "displayLabel": "string",
  • "displayName": "string",
  • "isConfigured": true,
  • "jit": {
    },
  • "keywords": [
    ],
  • "learnMore": "string",
  • "logo": {
    },
  • "name": "string",
  • "oidc": {
    },
  • "provision": {
    },
  • "sso": {
    },
  • "ssoUrl": "string",
  • "status": "",
  • "test": "string"
}

Applications

Applications

The endpoint returns all your SSO / SAML Applications.

Sample Request

curl -X GET https://console.jumpcloud.com/api/applications \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["applications","applications.readonly"]
Authorizations:
x-api-key
query Parameters
fields
string

The space separated fields included in the returned records. If omitted the default list of fields will be returned.

limit
integer

The number of records to return at once.

skip
integer

The offset into the records to return.

sort
string
Default: "name"

The space separated fields used to sort the collection. Default sort is ascending, prefix with - to sort descending.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/applications?fields=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE&skip=SOME_INTEGER_VALUE&sort=name&filter=SOME_STRING_VALUE' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "name": "string",
  • "results": [
    ],
  • "totalCount": 0
}

Create an Application

The endpoint adds a new SSO / SAML Applications.

scopes: ["applications"]
Authorizations:
x-api-key
header Parameters
x-org-id
string
Default:
Request Body schema: application/json
_id
string
active
boolean
beta
boolean
color
string
Enum: "" "#202D38" "#005466" "#3E8696" "#006CAC" "#0617AC" "#7C6ADA" "#D5779D" "#9E2F00" "#FFB000" "#58C469" "#57C49F" "#FF6C03"
required
object
created
string
databaseAttributes
Array of objects
description
string <= 256 characters
displayLabel
string
displayName
string
learnMore
string
object
name
required
string
organization
string
object (sso)
ssoUrl
required
string

Responses

Request samples

Content type
application/json
{
  • "_id": "string",
  • "active": true,
  • "beta": true,
  • "color": "",
  • "config": {
    },
  • "created": "string",
  • "databaseAttributes": [
    ],
  • "description": "string",
  • "displayLabel": "string",
  • "displayName": "string",
  • "learnMore": "string",
  • "logo": {
    },
  • "name": "string",
  • "organization": "string",
  • "sso": {
    },
  • "ssoUrl": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "active": true,
  • "beta": true,
  • "color": "",
  • "config": {
    },
  • "created": "string",
  • "databaseAttributes": [
    ],
  • "description": "string",
  • "displayLabel": "string",
  • "displayName": "string",
  • "learnMore": "string",
  • "logo": {
    },
  • "name": "string",
  • "organization": "string",
  • "sso": {
    },
  • "ssoUrl": "string"
}

Delete an Application

The endpoint deletes an SSO / SAML Application.

scopes: ["applications"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request DELETE \
  --url https://console.jumpcloud.com/api/applications/{id} \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "_id": "string",
  • "active": true,
  • "beta": true,
  • "color": "",
  • "config": {
    },
  • "created": "string",
  • "databaseAttributes": [
    ],
  • "description": "string",
  • "displayLabel": "string",
  • "displayName": "string",
  • "learnMore": "string",
  • "logo": {
    },
  • "name": "string",
  • "organization": "string",
  • "sso": {
    },
  • "ssoUrl": "string"
}

Get an Application

The endpoint retrieves an SSO / SAML Application.

scopes: ["applications","applications.readonly"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url https://console.jumpcloud.com/api/applications/{id} \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "_id": "string",
  • "active": true,
  • "beta": true,
  • "color": "",
  • "config": {
    },
  • "created": "string",
  • "databaseAttributes": [
    ],
  • "description": "string",
  • "displayLabel": "string",
  • "displayName": "string",
  • "learnMore": "string",
  • "logo": {
    },
  • "name": "string",
  • "organization": "string",
  • "sso": {
    },
  • "ssoUrl": "string"
}

Update an Application

The endpoint updates a SSO / SAML Application. Any fields not provided will be reset or created with default values.

scopes: ["applications"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:
Request Body schema: application/json
_id
string
active
boolean
beta
boolean
color
string
Enum: "" "#202D38" "#005466" "#3E8696" "#006CAC" "#0617AC" "#7C6ADA" "#D5779D" "#9E2F00" "#FFB000" "#58C469" "#57C49F" "#FF6C03"
required
object
created
string
databaseAttributes
Array of objects
description
string <= 256 characters
displayLabel
string
displayName
string
learnMore
string
object
name
required
string
organization
string
object (sso)
ssoUrl
required
string

Responses

Request samples

Content type
application/json
{
  • "_id": "string",
  • "active": true,
  • "beta": true,
  • "color": "",
  • "config": {
    },
  • "created": "string",
  • "databaseAttributes": [
    ],
  • "description": "string",
  • "displayLabel": "string",
  • "displayName": "string",
  • "learnMore": "string",
  • "logo": {
    },
  • "name": "string",
  • "organization": "string",
  • "sso": {
    },
  • "ssoUrl": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "active": true,
  • "beta": true,
  • "color": "",
  • "config": {
    },
  • "created": "string",
  • "databaseAttributes": [
    ],
  • "description": "string",
  • "displayLabel": "string",
  • "displayName": "string",
  • "learnMore": "string",
  • "logo": {
    },
  • "name": "string",
  • "organization": "string",
  • "sso": {
    },
  • "ssoUrl": "string"
}

Command Results

List all Command Results

This endpoint returns all command results.

Sample Request

curl -X GET https://console.jumpcloud.com/api/commandresults \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key:{API_KEY}'

To filter command results use the Search API

scopes: ["commands","commands.readonly"]
Authorizations:
x-api-key
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

limit
integer
Default: 10

The number of records to return at once. Limited to 100.

skip
integer >= 0
Default: 0

The offset into the records to return.

sort
string
Default: ""

Use space separated sort parameters to sort the collection. Default sort is ascending. Prefix with - to sort descending.

header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/commandresults?fields=&limit=10&skip=0&sort=' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Delete a Command result

This endpoint deletes a specific command result.

Sample Request

curl -X DELETE https://console.jumpcloud.com/api/commandresults/{CommandID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["commands"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request DELETE \
  --url https://console.jumpcloud.com/api/commandresults/{id} \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "_id": "string",
  • "command": "string",
  • "files": [
    ],
  • "name": "string",
  • "organization": "string",
  • "requestTime": "2019-08-24T14:15:22Z",
  • "response": {
    },
  • "responseTime": "2019-08-24T14:15:22Z",
  • "sudo": true,
  • "system": "string",
  • "systemId": "string",
  • "user": "string",
  • "workflowId": "string",
  • "workflowInstanceId": "string"
}

List an individual Command result

This endpoint returns a specific command result.

Sample Request

curl -X GET https://console.jumpcloud.com/api/commandresults/{CommandResultID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["commands","commands.readonly"]
Authorizations:
x-api-key
path Parameters
id
required
string
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/commandresults/{id}?fields=&filter=SOME_STRING_VALUE' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "_id": "string",
  • "command": "string",
  • "files": [
    ],
  • "name": "string",
  • "organization": "string",
  • "requestTime": "2019-08-24T14:15:22Z",
  • "response": {
    },
  • "responseTime": "2019-08-24T14:15:22Z",
  • "sudo": true,
  • "system": "string",
  • "systemId": "string",
  • "user": "string",
  • "workflowId": "string",
  • "workflowInstanceId": "string"
}

Command Triggers

Launch a command via a Trigger

This endpoint allows you to launch a command based on a defined trigger.

Sample Requests

Launch a Command via a Trigger

curl --silent \
     -X 'POST' \
     -H "x-api-key: {API_KEY}" \
     "https://console.jumpcloud.com/api/command/trigger/{TriggerName}"

Launch a Command via a Trigger passing a JSON object to the command

curl --silent \
     -X 'POST' \
     -H "x-api-key: {API_KEY}" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d '{ "srcip":"192.168.2.32", "attack":"Cross Site Scripting Attempt" }' \
     "https://console.jumpcloud.com/api/command/trigger/{TriggerName}"
scopes: ["commands","commands.schedule"]
Authorizations:
x-api-key
path Parameters
triggername
required
string
header Parameters
x-org-id
string
Default:
Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "triggered": [
    ]
}

Commands

List All Commands

This endpoint returns all commands.

Sample Request

curl -X GET https://console.jumpcloud.com/api/commands/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["commands","commands.readonly"]
Authorizations:
x-api-key
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
limit
integer
Default: 10

The number of records to return at once. Limited to 100.

skip
integer >= 0
Default: 0

The offset into the records to return.

sort
string
Default: ""

Use space separated sort parameters to sort the collection. Default sort is ascending. Prefix with - to sort descending.

header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/commands?fields=&filter=SOME_STRING_VALUE&limit=10&skip=0&sort=' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Create A Command

This endpoint allows you to create a new command.

NOTE: the system property in the command is not used. Use a POST to /api/v2/commands/{id}/associations to bind a command to a system.

Sample Request

curl -X POST https://console.jumpcloud.com/api/commands/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json'
  -H 'x-api-key: {API_KEY}'
  -d '{"name":"Test API Command", "command":"String", "user":"{UserID}", "schedule":"", "timeout":"100"}'
scopes: ["commands"]
Authorizations:
x-api-key
header Parameters
x-org-id
string
Default:
Request Body schema: application/json
command
required
string

The command to execute on the server.

commandRunners
Array of strings

An array of IDs of the Command Runner Users that can execute this command.

commandType
required
string
Default: "linux"

The Command OS

files
Array of strings

An array of file IDs to include with the command.

launchType
string

How the command will execute.

listensTo
string
name
required
string
organization
string

The ID of the organization.

schedule
string

A crontab that consists of: [ (seconds) (minutes) (hours) (days of month) (months) (weekdays) ] or [ immediate ]. If you send this as an empty string, it will run immediately.

scheduleRepeatType
string

When the command will repeat.

scheduleYear
integer

The year that a scheduled command will launch in.

shell
string

The shell used to run the command.

sudo
boolean
systems
Array of strings

Not used. Use /api/v2/commands/{id}/associations to bind commands to systems.

template
string

The template this command was created from

timeToLiveSeconds
integer

Time in seconds a command can wait in the queue to be run before timing out

timeout
string

The time in seconds to allow the command to run for. The maximum value is 86400 seconds (1 day).

trigger
string

The name of the command trigger.

user
string

The ID of the system user to run the command as. This field is required when creating a command with a commandType of "mac" or "linux".

Responses

Request samples

Content type
application/json
{
  • "command": "string",
  • "commandRunners": [
    ],
  • "commandType": "linux",
  • "files": [
    ],
  • "launchType": "string",
  • "listensTo": "string",
  • "name": "string",
  • "organization": "string",
  • "schedule": "string",
  • "scheduleRepeatType": "string",
  • "scheduleYear": 0,
  • "shell": "string",
  • "sudo": true,
  • "systems": [
    ],
  • "template": "string",
  • "timeToLiveSeconds": 0,
  • "timeout": "string",
  • "trigger": "string",
  • "user": "string"
}

Response samples

Content type
application/json
{
  • "command": "string",
  • "commandRunners": [
    ],
  • "commandType": "linux",
  • "files": [
    ],
  • "launchType": "string",
  • "listensTo": "string",
  • "name": "string",
  • "organization": "string",
  • "schedule": "string",
  • "scheduleRepeatType": "string",
  • "scheduleYear": 0,
  • "shell": "string",
  • "sudo": true,
  • "systems": [
    ],
  • "template": "string",
  • "timeToLiveSeconds": 0,
  • "timeout": "string",
  • "trigger": "string",
  • "user": "string"
}

Delete a Command

This endpoint deletes a specific command based on the Command ID.

Sample Request

curl -X DELETE https://console.jumpcloud.com/api/commands/{CommandID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["commands"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request DELETE \
  --url https://console.jumpcloud.com/api/commands/{id} \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "command": "string",
  • "commandRunners": [
    ],
  • "commandType": "linux",
  • "files": [
    ],
  • "launchType": "string",
  • "listensTo": "string",
  • "name": "string",
  • "organization": "string",
  • "schedule": "string",
  • "scheduleRepeatType": "string",
  • "scheduleYear": 0,
  • "shell": "string",
  • "sudo": true,
  • "systems": [
    ],
  • "template": "string",
  • "timeToLiveSeconds": 0,
  • "timeout": "string",
  • "trigger": "string",
  • "user": "string"
}

List an individual Command

This endpoint returns a specific command based on the command ID.

Sample Request

curl -X GET https://console.jumpcloud.com/api/commands/{CommandID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["commands","commands.readonly"]
Authorizations:
x-api-key
path Parameters
id
required
string
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/commands/{id}?fields=' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "command": "string",
  • "commandRunners": [
    ],
  • "commandType": "linux",
  • "files": [
    ],
  • "launchType": "string",
  • "listensTo": "string",
  • "name": "string",
  • "organization": "string",
  • "schedule": "string",
  • "scheduleRepeatType": "string",
  • "scheduleYear": 0,
  • "shell": "string",
  • "sudo": true,
  • "systems": [
    ],
  • "template": "string",
  • "timeToLiveSeconds": 0,
  • "timeout": "string",
  • "trigger": "string",
  • "user": "string"
}

Update a Command

This endpoint Updates a command based on the command ID and returns the modified command record.

Sample Request

curl -X PUT https://console.jumpcloud.com/api/commands/{CommandID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
    "name":"Test API Command",
    "command":"String",
    "user":"{UserID}",
    "schedule":"",
    "timeout":"100"
}'
scopes: ["commands"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:
Request Body schema: application/json
command
required
string

The command to execute on the server.

commandRunners
Array of strings

An array of IDs of the Command Runner Users that can execute this command.

commandType
required
string
Default: "linux"

The Command OS

files
Array of strings

An array of file IDs to include with the command.

launchType
string

How the command will execute.

listensTo
string
name
required
string
organization
string

The ID of the organization.

schedule
string

A crontab that consists of: [ (seconds) (minutes) (hours) (days of month) (months) (weekdays) ] or [ immediate ]. If you send this as an empty string, it will run immediately.

scheduleRepeatType
string

When the command will repeat.

scheduleYear
integer

The year that a scheduled command will launch in.

shell
string

The shell used to run the command.

sudo
boolean
systems
Array of strings

Not used. Use /api/v2/commands/{id}/associations to bind commands to systems.

template
string

The template this command was created from

timeToLiveSeconds
integer

Time in seconds a command can wait in the queue to be run before timing out

timeout
string

The time in seconds to allow the command to run for. The maximum value is 86400 seconds (1 day).

trigger
string

The name of the command trigger.

user
string

The ID of the system user to run the command as. This field is required when creating a command with a commandType of "mac" or "linux".

Responses

Request samples

Content type
application/json
{
  • "command": "string",
  • "commandRunners": [
    ],
  • "commandType": "linux",
  • "files": [
    ],
  • "launchType": "string",
  • "listensTo": "string",
  • "name": "string",
  • "organization": "string",
  • "schedule": "string",
  • "scheduleRepeatType": "string",
  • "scheduleYear": 0,
  • "shell": "string",
  • "sudo": true,
  • "systems": [
    ],
  • "template": "string",
  • "timeToLiveSeconds": 0,
  • "timeout": "string",
  • "trigger": "string",
  • "user": "string"
}

Response samples

Content type
application/json
{
  • "command": "string",
  • "commandRunners": [
    ],
  • "commandType": "linux",
  • "files": [
    ],
  • "launchType": "string",
  • "listensTo": "string",
  • "name": "string",
  • "organization": "string",
  • "schedule": "string",
  • "scheduleRepeatType": "string",
  • "scheduleYear": 0,
  • "shell": "string",
  • "sudo": true,
  • "systems": [
    ],
  • "template": "string",
  • "timeToLiveSeconds": 0,
  • "timeout": "string",
  • "trigger": "string",
  • "user": "string"
}

Get results for a specific command

This endpoint returns results for a specific command.

Sample Request

curl -X GET https://console.jumpcloud.com/api/commands/{id}/results \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["commands","commands.readonly"]
Authorizations:
x-api-key
path Parameters
id
required
string
query Parameters
limit
integer
Default: 10

The number of records to return at once. Limited to 100.

skip
integer >= 0
Default: 0

The offset into the records to return.

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/commands/{id}/results?limit=10&skip=0' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
[
  • {
    }
]

Get a Command File

This endpoint returns the uploaded file(s) associated with a specific command.

Sample Request

curl -X GET https://console.jumpcloud.com/api/files/command/{commandID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["commands","commands.readonly"]
Authorizations:
x-api-key
path Parameters
id
required
string
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

limit
integer
Default: 10

The number of records to return at once. Limited to 100.

skip
integer >= 0
Default: 0

The offset into the records to return.

header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/files/command/{id}?fields=&limit=10&skip=0' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Run a command

This endpoint allows you to run a command.

Sample Request

curl -X POST https://console.jumpcloud.com/api/runCommand \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
  -d '{"_id":"{commandID}", "systemIds":["systemId"]}'
scopes: ["commands","commands.schedule"]
Authorizations:
x-api-key
Request Body schema: application/json
_id
string

The ID of the command.

systemIds
Array of strings

An optional list of device IDs to run the command on. If omitted, the command will run on devices bound to the command.

Responses

Request samples

Content type
application/json
{
  • "_id": "string",
  • "systemIds": [
    ]
}

Response samples

Content type
application/json
{
  • "queueIds": [
    ],
  • "workflowInstanceId": "string"
}

Managed Service Provider

Get Organization Details

This endpoint returns Organization Details.

Sample Request

curl -X GET \
  https://console.jumpcloud.com/api/organizations \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["commandrunner.legacy","organizations","organizations.readonly"]
Authorizations:
x-api-key
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
limit
integer
Default: 10

The number of records to return at once. Limited to 100.

search
string

A nested object containing a searchTerm string or array of strings and a list of fields to search on.

skip
integer >= 0
Default: 0

The offset into the records to return.

sort
string
Default: ""

Use space separated sort parameters to sort the collection. Default sort is ascending. Prefix with - to sort descending.

sortIgnoreCase
string
Default: ""

Use space separated sort parameters to sort the collection, ignoring case. Default sort is ascending. Prefix with - to sort descending.

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/organizations?fields=&filter=SOME_STRING_VALUE&limit=10&search=SOME_STRING_VALUE&skip=0&sort=&sortIgnoreCase=' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Administrator Password Reset Initiation

This endpoint triggers the sending of a reactivation e-mail to an administrator.

scopes: ["administrators"]
Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Request samples

curl --request GET \
  --url https://console.jumpcloud.com/api/users/reactivate/{id} \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "status": "string"
}

Administrator TOTP Reset Initiation

This endpoint initiates a TOTP reset for an admin. This request does not accept a body.

scopes: ["administrators"]
Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Request samples

curl --request POST \
  --url https://console.jumpcloud.com/api/users/resettotp/{id} \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "status": "string"
}

Update a user

This endpoint allows you to update a user.

scopes: ["administrators"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:
Request Body schema: application/json
apiKeyAllowed
boolean
email
string <email> <= 1024 characters
enableMultiFactor
boolean
firstname
string
growthData
object
lastWhatsNewChecked
string <date>
lastname
string
roleName
string

Responses

Request samples

Content type
application/json
{
  • "apiKeyAllowed": true,
  • "email": "user@example.com",
  • "enableMultiFactor": true,
  • "firstname": "string",
  • "growthData": { },
  • "lastWhatsNewChecked": "2019-08-24",
  • "lastname": "string",
  • "roleName": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "apiKeyAllowed": true,
  • "apiKeyHash": {
    },
  • "apiKeySet": true,
  • "apiKeyUpdatedAt": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "disableIntroduction": true,
  • "email": "string",
  • "enableMultiFactor": true,
  • "firstname": "string",
  • "growthData": {
    },
  • "lastWhatsNewChecked": "2019-08-24T14:15:22Z",
  • "lastname": "string",
  • "organization": "string",
  • "passwordUpdatedAt": "2019-08-24T14:15:22Z",
  • "provider": "string",
  • "role": "string",
  • "roleName": "string",
  • "sessionCount": 0,
  • "suspended": true,
  • "totpEnrolled": true,
  • "totpUpdatedAt": "2019-08-24T14:15:22Z",
  • "usersTimeZone": "string"
}

Organizations

Get Organization Details

This endpoint returns Organization Details.

Sample Request

curl -X GET \
  https://console.jumpcloud.com/api/organizations \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["commandrunner.legacy","organizations","organizations.readonly"]
Authorizations:
x-api-key
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
limit
integer
Default: 10

The number of records to return at once. Limited to 100.

search
string

A nested object containing a searchTerm string or array of strings and a list of fields to search on.

skip
integer >= 0
Default: 0

The offset into the records to return.

sort
string
Default: ""

Use space separated sort parameters to sort the collection. Default sort is ascending. Prefix with - to sort descending.

sortIgnoreCase
string
Default: ""

Use space separated sort parameters to sort the collection, ignoring case. Default sort is ascending. Prefix with - to sort descending.

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/organizations?fields=&filter=SOME_STRING_VALUE&limit=10&search=SOME_STRING_VALUE&skip=0&sort=&sortIgnoreCase=' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Get an Organization

This endpoint returns a particular Organization.

Sample Request

curl -X GET https://console.jumpcloud.com/api/organizations/{OrganizationID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["organizations","organizations.readonly"]
Authorizations:
x-api-key
path Parameters
id
required
string
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/organizations/{id}?fields=&filter=SOME_STRING_VALUE' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "_id": "string",
  • "accessRestriction": "string",
  • "accountsReceivable": "string",
  • "created": "string",
  • "customEmailSettings": {
    },
  • "displayName": "string",
  • "entitlement": {
    },
  • "hasCreditCard": true,
  • "hasStripeCustomerId": true,
  • "lastEstimateCalculationTimeStamp": "string",
  • "lastSfdcSyncStatus": { },
  • "logoUrl": "string",
  • "provider": "string",
  • "settings": {
    },
  • "totalBillingEstimate": 0
}

Update an Organization

This endpoint allows you to update an Organization.

Note: passwordPolicy settings are only used when passwordCompliance is set to "custom". We discourage the use of non-custom passwordCompliance values.

emailDisclaimer can only be modified by paying customers.

hasStripeCustomerId is deprecated and will be removed.

Sample Request

curl -X PUT https://console.jumpcloud.com/api/organizations/{OrganizationID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "settings": {
    "contactName": "Admin Name",
    "contactEmail": "admin@company.com",
    "systemUsersCanEdit":true,
    "passwordPolicy": {
      "enableMaxHistory": true,
      "maxHistory": 3
    }
  }
}'
scopes: ["organizations"]
Authorizations:
x-api-key
path Parameters
id
required
string
Request Body schema: application/json
object (OrganizationSettingsPut)

Responses

Request samples

Content type
application/json
{
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "accessRestriction": "string",
  • "accountsReceivable": "string",
  • "created": "string",
  • "customEmailSettings": {
    },
  • "displayName": "string",
  • "entitlement": {
    },
  • "hasCreditCard": true,
  • "hasStripeCustomerId": true,
  • "lastEstimateCalculationTimeStamp": "string",
  • "lastSfdcSyncStatus": { },
  • "logoUrl": "string",
  • "provider": "string",
  • "settings": {
    },
  • "totalBillingEstimate": 0
}

Radius Servers

List Radius Servers

This endpoint allows you to get a list of all RADIUS servers in your organization.

Sample Request

curl -X GET https://console.jumpcloud.com/api/radiusservers/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
scopes: ["radius","radius.readonly"]
Authorizations:
x-api-key
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
limit
integer
Default: 10

The number of records to return at once. Limited to 100.

skip
integer >= 0
Default: 0

The offset into the records to return.

sort
string
Default: ""

Use space separated sort parameters to sort the collection. Default sort is ascending. Prefix with - to sort descending.

header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/radiusservers?fields=&filter=SOME_STRING_VALUE&limit=10&skip=0&sort=' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Create a Radius Server

This endpoint allows you to create RADIUS servers in your organization.

Sample Request

curl -X POST https://console.jumpcloud.com/api/radiusservers/ \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
    "name": "{test_radius}",
    "networkSourceIp": "{0.0.0.0}",
    "sharedSecret":"{secretpassword}",
    "userLockoutAction": "REMOVE",
    "userPasswordExpirationAction": "MAINTAIN"
}'
scopes: ["radius"]
Authorizations:
x-api-key
header Parameters
x-org-id
string
Default:
Request Body schema: application/json
authIdp
string
Enum: "JUMPCLOUD" "AZURE"
caCert
string
deviceCertEnabled
boolean
mfa
string
Enum: "DISABLED" "ENABLED" "REQUIRED" "ALWAYS"
name
required
string
networkSourceIp
required
string
requireTlsAuth
boolean
sharedSecret
required
string

RADIUS shared secret between the server and client.

tagNames
Array of strings
userCertEnabled
boolean
userLockoutAction
string
userPasswordEnabled
boolean
userPasswordExpirationAction
string

Responses

Request samples

Content type
application/json
{
  • "authIdp": "JUMPCLOUD",
  • "caCert": "string",
  • "deviceCertEnabled": true,
  • "mfa": "DISABLED",
  • "name": "string",
  • "networkSourceIp": "string",
  • "requireTlsAuth": true,
  • "sharedSecret": "string",
  • "tagNames": [
    ],
  • "userCertEnabled": true,
  • "userLockoutAction": "string",
  • "userPasswordEnabled": true,
  • "userPasswordExpirationAction": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "authIdp": "JUMPCLOUD",
  • "caCert": "string",
  • "deviceCertEnabled": true,
  • "mfa": "DISABLED",
  • "name": "string",
  • "networkSourceIp": "string",
  • "organization": "string",
  • "requireTlsAuth": true,
  • "sharedSecret": "string",
  • "tagNames": [
    ],
  • "tags": [
    ],
  • "userCertEnabled": true,
  • "userLockoutAction": "string",
  • "userPasswordEnabled": true,
  • "userPasswordExpirationAction": "string"
}

Delete Radius Server

This endpoint allows you to delete RADIUS servers in your organization.

curl -X DELETE https://console.jumpcloud.com/api/radiusservers/{ServerID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
scopes: ["radius"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request DELETE \
  --url https://console.jumpcloud.com/api/radiusservers/{id} \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "_id": "string",
  • "authIdp": "JUMPCLOUD",
  • "caCert": "string",
  • "deviceCertEnabled": true,
  • "mfa": "DISABLED",
  • "name": "string",
  • "networkSourceIp": "string",
  • "requireTlsAuth": true,
  • "tagNames": [
    ],
  • "userCertEnabled": true,
  • "userLockoutAction": "string",
  • "userPasswordEnabled": true,
  • "userPasswordExpirationAction": "string"
}

Get Radius Server

This endpoint allows you to get a RADIUS server in your organization.

curl -X PUT https://console.jumpcloud.com/api/radiusservers/{ServerID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
scopes: ["radius","radius.readonly"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url https://console.jumpcloud.com/api/radiusservers/{id} \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "_id": "string",
  • "authIdp": "JUMPCLOUD",
  • "caCert": "string",
  • "deviceCertEnabled": true,
  • "mfa": "DISABLED",
  • "name": "string",
  • "networkSourceIp": "string",
  • "organization": "string",
  • "requireTlsAuth": true,
  • "sharedSecret": "string",
  • "tagNames": [
    ],
  • "tags": [
    ],
  • "userCertEnabled": true,
  • "userLockoutAction": "string",
  • "userPasswordEnabled": true,
  • "userPasswordExpirationAction": "string"
}

Update Radius Servers

This endpoint allows you to update RADIUS servers in your organization.

curl -X PUT https://console.jumpcloud.com/api/radiusservers/{ServerID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
    "name": "{name_update}",
    "networkSourceIp": "{0.0.0.0}",
    "sharedSecret": "{secret_password}",
    "userLockoutAction": "REMOVE",
    "userPasswordExpirationAction": "MAINTAIN"
}'
scopes: ["radius"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:
Request Body schema: application/json
caCert
string
deviceCertEnabled
boolean
mfa
string
Enum: "DISABLED" "ENABLED" "REQUIRED" "ALWAYS"
name
required
string
networkSourceIp
required
string
requireTlsAuth
boolean
sharedSecret
required
string
tags
Array of strings
userCertEnabled
boolean
userLockoutAction
string
userPasswordEnabled
boolean
userPasswordExpirationAction
string

Responses

Request samples

Content type
application/json
{
  • "name": "test radius",
  • "networkSourceIp": "0.0.0.0",
  • "sharedSecret": "secretradiuspassword",
  • "tagsNames": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "authIdp": "JUMPCLOUD",
  • "caCert": "string",
  • "deviceCertEnabled": true,
  • "mfa": "DISABLED",
  • "name": "string",
  • "networkSourceIp": "string",
  • "requireTlsAuth": true,
  • "tagNames": [
    ],
  • "userCertEnabled": true,
  • "userLockoutAction": "string",
  • "userPasswordEnabled": true,
  • "userPasswordExpirationAction": "string"
}

Search

Search Commands Results

Return Command Results in multi-record format allowing for the passing of the filter parameter.

To support advanced filtering you can use the filter and searchFilter parameters that can only be passed in the body of POST /api/search/commandresults route. The filter parameter must be passed as Content-Type application/json.

The filter parameter is an object with a single property, either and or or with the value of the property being an array of query expressions.

This allows you to filter records using the logic of matching ALL or ANY records in the array of query expressions. If the and or or are not included the default behavior is to match ALL query expressions.

Sample Request

Exact search for a specific command result

curl -X POST https://console.jumpcloud.com/api/search/commandresults \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "filter" : "workflowInstanceId:$eq:62f3c599ec4e928499069c7f",
  "fields" : "name workflowId sudo"
}'
scopes: ["commands","commands.readonly"]
Authorizations:
x-api-key
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
limit
integer
Default: 10

The number of records to return at once. Limited to 100.

skip
integer >= 0
Default: 0

The offset into the records to return.

header Parameters
x-org-id
string
Default:
Request Body schema: application/json
fields
string
filter
object
searchFilter
object

Responses

Request samples

Content type
application/json
{
  • "fields": "string",
  • "filter": { },
  • "searchFilter": { }
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Search Commands

Return Commands in multi-record format allowing for the passing of the filter and searchFilter parameters. This WILL NOT allow you to add a new command. To support advanced filtering you can use the filter and searchFilter parameters that can only be passed in the body of POST /api/search/* routes. The filter and searchFilter parameters must be passed as Content-Type application/json. The filter parameter is an object with a single property, either and or or with the value of the property being an array of query expressions. This allows you to filter records using the logic of matching ALL or ANY records in the array of query expressions. If the and or or are not included the default behavior is to match ALL query expressions. The searchFilter parameter allows text searching on supported fields by specifying a searchTerm and a list of fields to query on. If any field has a partial text match on the searchTerm the record will be returned.

Sample Request

Exact search for a list of commands in a launchType

curl -X POST https://console.jumpcloud.com/api/search/commands \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "filter" : [{"launchType" : "repeated"}],
  "fields" : "name launchType sudo"
}'

Text search for commands with name

curl -X POST https://console.jumpcloud.com/api/search/commands \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "searchFilter" : {
    "searchTerm": "List",
    "fields": ["name"]
  },
  "fields" : "name launchType sudo"
}'

Text search for multiple commands

curl -X POST https://console.jumpcloud.com/api/search/commands \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "searchFilter" : {
    "searchTerm": ["List", "Log"],
    "fields": ["name"]
  },
  "fields" : "name launchType sudo"
}'

Combining filter and searchFilter to text search for commands with name who are in a list of launchType

curl -X POST https://console.jumpcloud.com/api/search/commands \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "searchFilter": {
    "searchTerm": "List",
    "fields": ["name"]
  },
  "filter": {
    "or": [
      {"launchType" : "repeated"},
      {"launchType" : "one-time"}
    ]
  },
  "fields" : "name launchType sudo"
}'
scopes: ["commands","commands.readonly"]
Authorizations:
x-api-key
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
limit
integer
Default: 10

The number of records to return at once. Limited to 100.

skip
integer >= 0
Default: 0

The offset into the records to return.

header Parameters
x-org-id
string
Default:
Request Body schema: application/json
fields
string
filter
object
searchFilter
object

Responses

Request samples

Content type
application/json
{
  • "fields": "string",
  • "filter": { },
  • "searchFilter": { }
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Search Organizations

This endpoint will return Organization data based on your search parameters. This endpoint WILL NOT allow you to add a new Organization.

You can use the supported parameters and pass those in the body of request.

The parameters must be passed as Content-Type application/json.

Sample Request

curl -X POST https://console.jumpcloud.com/api/search/organizations \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "search":{
    "fields" : ["settings.name"],
    "searchTerm": "Second"
    },
  "fields": ["_id", "displayName", "logoUrl"],
  "limit" : 0,
  "skip" : 0
}'
scopes: ["commandrunner.legacy","organizations","organizations.readonly"]
Authorizations:
x-api-key
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
limit
integer
Default: 10

The number of records to return at once. Limited to 100.

skip
integer >= 0
Default: 0

The offset into the records to return.

Request Body schema: application/json
fields
string
filter
object
searchFilter
object

Responses

Request samples

Content type
application/json
{
  • "fields": "string",
  • "filter": { },
  • "searchFilter": { }
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Search Systems

Return Systems in multi-record format allowing for the passing of the filter and searchFilter parameters. This WILL NOT allow you to add a new system.

To support advanced filtering you can use the filter and searchFilter parameters that can only be passed in the body of POST /api/search/* routes. The filter and searchFilter parameters must be passed as Content-Type application/json.

The filter parameter is an object with a single property, either and or or with the value of the property being an array of query expressions.

This allows you to filter records using the logic of matching ALL or ANY records in the array of query expressions. If the and or or are not included the default behavior is to match ALL query expressions.

The searchFilter parameter allows text searching on supported fields by specifying a searchTerm and a list of fields to query on. If any field has a partial text match on the searchTerm the record will be returned.

Sample Request

Exact search for a list of hostnames

curl -X POST https://console.jumpcloud.com/api/search/systems \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "filter": {
    "or": [
      {"hostname" : "my-hostname"},
      {"hostname" : "other-hostname"}
    ]
  },
  "fields" : "os hostname displayName"
}'

Text search for a hostname or display name

curl -X POST https://console.jumpcloud.com/api/search/systems \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "searchFilter": {
    "searchTerm": "my-host",
    "fields": ["hostname", "displayName"]
  },
  "fields": "os hostname displayName"
}'

Text search for a multiple hostnames.

curl -X POST https://console.jumpcloud.com/api/search/systems \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "searchFilter": {
    "searchTerm": ["my-host", "my-other-host"],
    "fields": ["hostname"]
  },
  "fields": "os hostname displayName"
}'

Combining filter and searchFilter to search for names that match a given OS

curl -X POST https://console.jumpcloud.com/api/search/systems \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "searchFilter": {
    "searchTerm": "my-host",
    "fields": ["hostname", "displayName"]
  },
  "filter": {
    "or": [
      {"os" : "Ubuntu"},
      {"os" : "Mac OS X"}
    ]
  },
  "fields": "os hostname displayName"
}'
scopes: ["systems","systems.readonly","commandrunner.legacy"]
Authorizations:
x-api-key
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

limit
integer
Default: 10

The number of records to return at once. Limited to 100.

skip
integer >= 0
Default: 0

The offset into the records to return.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
header Parameters
x-org-id
string
Default:
x-eventually-consistent
boolean
Default: false

EXPERIMENTAL! Use to acknowledge eventually consistent data in response.

Request Body schema: application/json
fields
string
filter
object
searchFilter
object

Responses

Request samples

Content type
application/json
{
  • "fields": "string",
  • "filter": { },
  • "searchFilter": { }
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Search System Users

Return System Users in multi-record format allowing for the passing of the filter and searchFilter parameters. This WILL NOT allow you to add a new system user.

To support advanced filtering you can use the filter and searchFilter parameters that can only be passed in the body of POST /api/search/* routes. The filter and searchFilter parameters must be passed as Content-Type application/json.

The filter parameter is an object with a single property, either and or or with the value of the property being an array of query expressions.

This allows you to filter records using the logic of matching ALL or ANY records in the array of query expressions. If the and or or are not included the default behavior is to match ALL query expressions.

The searchFilter parameter allows text searching on supported fields by specifying a searchTerm and a list of fields to query on. If any field has a partial text match on the searchTerm the record will be returned.

Sample Request

Exact search for a list of system users in a department

curl -X POST https://console.jumpcloud.com/api/search/systemusers \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "filter" : [{"department" : "IT"}],
  "fields" : "email username sudo"
}'

Text search for system users with and email on a domain

curl -X POST https://console.jumpcloud.com/api/search/systemusers \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "searchFilter" : {
    "searchTerm": "@jumpcloud.com",
    "fields": ["email"]
  },
  "fields" : "email username sudo"
}'

Text search for multiple system users

curl -X POST https://console.jumpcloud.com/api/search/systemusers \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "searchFilter" : {
    "searchTerm": ["john", "sarah"],
    "fields": ["username"]
  },
  "fields" : "email username sudo"
}'

Combining filter and searchFilter to text search for system users with and email on a domain who are in a list of departments

curl -X POST https://console.jumpcloud.com/api/search/systemusers \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "searchFilter": {
    "searchTerm": "@jumpcloud.com",
    "fields": ["email"]
  },
  "filter": {
    "or": [
      {"department" : "IT"},
      {"department" : "Sales"}
    ]
  },
  "fields" : "email username sudo"
}'
scopes: ["users","users.readonly"]
Authorizations:
x-api-key
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
limit
integer
Default: 10

The number of records to return at once. Limited to 100.

skip
integer >= 0
Default: 0

The offset into the records to return.

header Parameters
x-org-id
string
Default:
x-eventually-consistent
boolean
Default: false

EXPERIMENTAL! Use to acknowledge eventually consistent data in response.

Request Body schema: application/json
fields
string
filter
object
searchFilter
object

Responses

Request samples

Content type
application/json
{
  • "fields": "string",
  • "filter": { },
  • "searchFilter": { }
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Systems

List All Systems

This endpoint returns all Systems.

Sample Requests

curl -X GET https://console.jumpcloud.com/api/systems \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["systems","systems.readonly"]
Authorizations:
x-api-key
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

limit
integer
Default: 10

The number of records to return at once. Limited to 100.

search
string

A nested object containing a searchTerm string or array of strings and a list of fields to search on.

skip
integer >= 0
Default: 0

The offset into the records to return.

sort
string
Default: ""

Use space separated sort parameters to sort the collection. Default sort is ascending. Prefix with - to sort descending.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/systems?fields=&limit=10&search=SOME_STRING_VALUE&skip=0&sort=&filter=SOME_STRING_VALUE' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Delete a System

This endpoint allows you to delete a system. This command will cause the system to uninstall the JumpCloud agent from its self which can can take about a minute. If the system is not connected to JumpCloud the system record will simply be removed.

Sample Request

curl -X DELETE https://console.jumpcloud.com/api/systems/{SystemID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["systems","systems.self"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
Date
string

Current date header for the System Context API

Authorization
string

Authorization header for the System Context API

x-org-id
string
Default:

Responses

Request samples

curl --request DELETE \
  --url https://console.jumpcloud.com/api/systems/{id} \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "_id": "string",
  • "active": true,
  • "agentVersion": "string",
  • "allowMultiFactorAuthentication": true,
  • "allowPublicKeyAuthentication": true,
  • "allowSshPasswordAuthentication": true,
  • "allowSshRootLogin": true,
  • "amazonInstanceID": "string",
  • "arch": "string",
  • "archFamily": "string",
  • "azureAdJoined": true,
  • "builtInCommands": [
    ],
  • "connectionHistory": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "desktopCapable": true,
  • "displayManager": "string",
  • "displayName": "string",
  • "domainInfo": {
    },
  • "fde": {
    },
  • "fileSystem": "string",
  • "hasServiceAccount": true,
  • "hostname": "string",
  • "hwVendor": "string",
  • "isPolicyBound": true,
  • "lastContact": "2019-08-24T14:15:22Z",
  • "mdm": {
    },
  • "modifySSHDConfig": true,
  • "networkInterfaces": [
    ],
  • "organization": "string",
  • "os": "string",
  • "osFamily": "string",
  • "osVersionDetail": {
    },
  • "policyStats": {
    },
  • "primarySystemUser": {
    },
  • "provisionMetadata": {
    },
  • "remoteAssistAgentVersion": "string",
  • "remoteIP": "string",
  • "secureLogin": {
    },
  • "serialNumber": "string",
  • "serviceAccountState": {
    },
  • "sshRootEnabled": true,
  • "sshdParams": [
    ],
  • "systemInsights": {
    },
  • "systemTimezone": 0,
  • "tags": [
    ],
  • "templateName": "string",
  • "userMetrics": [
    ],
  • "version": "string"
}

List an individual system

This endpoint returns an individual system.

Sample Request

curl -X GET https://console.jumpcloud.com/api/systems/{SystemID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["systems","systems.readonly","systems.self"]
Authorizations:
x-api-key
path Parameters
id
required
string
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
header Parameters
Date
string

Current date header for the System Context API

Authorization
string

Authorization header for the System Context API

x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/systems/{id}?fields=&filter=SOME_STRING_VALUE' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "_id": "string",
  • "active": true,
  • "agentVersion": "string",
  • "allowMultiFactorAuthentication": true,
  • "allowPublicKeyAuthentication": true,
  • "allowSshPasswordAuthentication": true,
  • "allowSshRootLogin": true,
  • "amazonInstanceID": "string",
  • "arch": "string",
  • "archFamily": "string",
  • "azureAdJoined": true,
  • "builtInCommands": [
    ],
  • "connectionHistory": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "desktopCapable": true,
  • "displayManager": "string",
  • "displayName": "string",
  • "domainInfo": {
    },
  • "fde": {
    },
  • "fileSystem": "string",
  • "hasServiceAccount": true,
  • "hostname": "string",
  • "hwVendor": "string",
  • "isPolicyBound": true,
  • "lastContact": "2019-08-24T14:15:22Z",
  • "mdm": {
    },
  • "modifySSHDConfig": true,
  • "networkInterfaces": [
    ],
  • "organization": "string",
  • "os": "string",
  • "osFamily": "string",
  • "osVersionDetail": {
    },
  • "policyStats": {
    },
  • "primarySystemUser": {
    },
  • "provisionMetadata": {
    },
  • "remoteAssistAgentVersion": "string",
  • "remoteIP": "string",
  • "secureLogin": {
    },
  • "serialNumber": "string",
  • "serviceAccountState": {
    },
  • "sshRootEnabled": true,
  • "sshdParams": [
    ],
  • "systemInsights": {
    },
  • "systemTimezone": 0,
  • "tags": [
    ],
  • "templateName": "string",
  • "userMetrics": [
    ],
  • "version": "string"
}

Update a system

This endpoint allows you to update a system.

Sample Request

curl -X PUT https://console.jumpcloud.com/api/systems/{SystemID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
    "displayName":"Name_Update",
    "allowSshPasswordAuthentication":"true",
    "allowSshRootLogin":"true",
    "allowMultiFactorAuthentication":"true",
    "allowPublicKeyAuthentication":"false"
}'
scopes: ["systems","systems.self"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
Date
string

Current date header for the System Context API

Authorization
string

Authorization header for the System Context API

x-org-id
string
Default:
Request Body schema: application/json
Array of objects
allowMultiFactorAuthentication
boolean
allowPublicKeyAuthentication
boolean
allowSshPasswordAuthentication
boolean
allowSshRootLogin
boolean
displayName
string
tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "agentBoundMessages": [
    ],
  • "allowMultiFactorAuthentication": true,
  • "allowPublicKeyAuthentication": true,
  • "allowSshPasswordAuthentication": true,
  • "allowSshRootLogin": true,
  • "displayName": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "active": true,
  • "agentVersion": "string",
  • "allowMultiFactorAuthentication": true,
  • "allowPublicKeyAuthentication": true,
  • "allowSshPasswordAuthentication": true,
  • "allowSshRootLogin": true,
  • "amazonInstanceID": "string",
  • "arch": "string",
  • "archFamily": "string",
  • "azureAdJoined": true,
  • "builtInCommands": [
    ],
  • "connectionHistory": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "desktopCapable": true,
  • "displayManager": "string",
  • "displayName": "string",
  • "domainInfo": {
    },
  • "fde": {
    },
  • "fileSystem": "string",
  • "hasServiceAccount": true,
  • "hostname": "string",
  • "hwVendor": "string",
  • "isPolicyBound": true,
  • "lastContact": "2019-08-24T14:15:22Z",
  • "mdm": {
    },
  • "modifySSHDConfig": true,
  • "networkInterfaces": [
    ],
  • "organization": "string",
  • "os": "string",
  • "osFamily": "string",
  • "osVersionDetail": {
    },
  • "policyStats": {
    },
  • "primarySystemUser": {
    },
  • "provisionMetadata": {
    },
  • "remoteAssistAgentVersion": "string",
  • "remoteIP": "string",
  • "secureLogin": {
    },
  • "serialNumber": "string",
  • "serviceAccountState": {
    },
  • "sshRootEnabled": true,
  • "sshdParams": [
    ],
  • "systemInsights": {
    },
  • "systemTimezone": 0,
  • "tags": [
    ],
  • "templateName": "string",
  • "userMetrics": [
    ],
  • "version": "string"
}

Erase a System

This endpoint allows you to run the erase command on the specified device. If a device is offline, the command will be run when the device becomes available. Only supported on Linux and Windows devices. Use Apple MDM security commands for macOS devices.

Sample Request

curl -X POST \
  https://console.jumpcloud.com/api/systems/{system_id}/command/builtin/erase \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d {}
scopes: ["systems"]
Authorizations:
x-api-key
path Parameters
system_id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request POST \
  --url https://console.jumpcloud.com/api/systems/{system_id}/command/builtin/erase \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "status": "string"
}

Lock a System

This endpoint allows you to run the lock command on the specified device. If a device is offline, the command will be run when the device becomes available. Only supported on Linux and Windows devices. Use Apple MDM security commands for macOS devices.

Sample Request

curl -X POST \
  https://console.jumpcloud.com/api/systems/{system_id}/command/builtin/lock \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d {}
scopes: ["systems"]
Authorizations:
x-api-key
path Parameters
system_id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request POST \
  --url https://console.jumpcloud.com/api/systems/{system_id}/command/builtin/lock \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "status": "string"
}

Restart a System

This endpoint allows you to run the restart command on the specified device. If a device is offline, the command will be run when the device becomes available. Only supported on Linux and Windows devices. Use Apple MDM security commands for macOS devices.

Sample Request

curl -X POST \
  https://console.jumpcloud.com/api/systems/{system_id}/command/builtin/restart \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d {}
scopes: ["systems"]
Authorizations:
x-api-key
path Parameters
system_id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request POST \
  --url https://console.jumpcloud.com/api/systems/{system_id}/command/builtin/restart \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "status": "string"
}

Shutdown a System

This endpoint allows you to run the shutdown command on the specified device. If a device is offline, the command will be run when the device becomes available. Only supported on Linux and Windows devices. Use Apple MDM security commands for macOS devices.

Sample Request

curl -X POST \
  https://console.jumpcloud.com/api/systems/{system_id}/command/builtin/shutdown \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d {}
scopes: ["systems"]
Authorizations:
x-api-key
path Parameters
system_id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request POST \
  --url https://console.jumpcloud.com/api/systems/{system_id}/command/builtin/shutdown \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "status": "string"
}

Systemusers

List all system users

This endpoint returns all systemusers.

Sample Request

curl -X GET https://console.jumpcloud.com/api/systemusers \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["commandrunner.legacy","users","users.readonly"]
Authorizations:
x-api-key
query Parameters
limit
integer
Default: 10

The number of records to return at once.

skip
integer
Default: 0

The offset into the records to return.

sort
string
Default: ""

The space separated fields used to sort the collection. Default sort is ascending, prefix with - to sort descending.

fields
string
Default: ""

The space separated fields included in the returned records. If omitted the default list of fields will be returned.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
search
string

A nested object containing a searchTerm string or array of strings and a list of fields to search on.

header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/systemusers?limit=10&skip=0&sort=&fields=&filter=SOME_STRING_VALUE&search=SOME_STRING_VALUE' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Create a system user

"This endpoint allows you to create a new system user.

Default User State

The state of the user can be explicitly passed in or omitted. If state is omitted from the request, then the user will get created using the value returned from the Get an Organization endpoint. The default user state for manually created users is stored in settings.newSystemUserStateDefaults.manualEntry

These default state values can be changed in the admin portal settings or by using the Update an Organization endpoint.

Sample Request

curl -X POST https://console.jumpcloud.com/api/systemusers \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-d '{
      "username":"{username}",
      "email":"{email_address}",
      "firstname":"{Name}",
      "lastname":"{Name}"
    }'
scopes: ["users"]
Authorizations:
x-api-key
query Parameters
fullValidationDetails
string

Pass this query parameter when a client wants all validation errors to be returned with a detailed error response for the form field specified. The current form fields are allowed:

  • password

Password validation flag

Use the password validation flag to receive details on a possible bad request response

?fullValidationDetails=password

Without the flag, default behavior will be a normal 400 with only a single validation string error

Expected Behavior

Clients can expect a list of validation error mappings for the validation query field in the details provided on the response:

{
  "code": 400,
  "message": "Password validation fail",
  "status": "INVALID_ARGUMENT",
  "details": [
      {
        "fieldViolationsList": [
          {"field": "password", "description": "specialCharacter"}
        ],
        '@type': 'type.googleapis.com/google.rpc.BadRequest',
      },
  ],
},
header Parameters
x-org-id
string
Default:
Request Body schema: application/json
account_locked
boolean
activated
boolean
Array of objects
allow_public_key
boolean
alternateEmail
string
Array of objects
company
string
costCenter
string
department
string
description
string <= 1024 characters
disableDeviceMaxLoginAttempts
boolean
displayname
string
email
required
string <= 1024 characters
employeeIdentifier
string <= 256 characters

Must be unique per user.

employeeType
string
enable_managed_uid
boolean
enable_user_portal_multifactor
boolean
external_dn
string
external_password_expiration_date
string <date-time>
external_source_type
string
externally_managed
boolean (externallymanagedpropertyinfo)

The externally_managed property has been deprecated. Whenever a user has their externally_managed field modified their restrictedFields property gets populated with the appropriate value, even if it is already set to a value an administrator manually set.

firstname
string
jobTitle
string
lastname
string
ldap_binding_user
boolean
location
string
managedAppleId
string <= 1024 characters
manager
string

Relation with another systemuser to identify the last as a manager.

object (mfa)
middlename
string
password
string
password_never_expires
boolean
passwordless_sudo
boolean
Array of objects
public_key
string
object
Array of objects
Array of objects (restrictedField)
samba_service_user
boolean
state
string
Enum: "STAGED" "ACTIVATED" "SUSPENDED"
sudo
boolean
suspended
boolean
tags
Array of strings
unix_guid
integer >= 1
unix_uid
integer >= 1
username
required
string

Responses

Request samples

Content type
application/json
{
  • "account_locked": true,
  • "activated": true,
  • "addresses": [
    ],
  • "allow_public_key": true,
  • "alternateEmail": "string",
  • "attributes": [
    ],
  • "company": "string",
  • "costCenter": "string",
  • "department": "string",
  • "description": "string",
  • "disableDeviceMaxLoginAttempts": true,
  • "displayname": "string",
  • "email": "string",
  • "employeeIdentifier": "string",
  • "employeeType": "string",
  • "enable_managed_uid": true,
  • "enable_user_portal_multifactor": true,
  • "external_dn": "string",
  • "external_password_expiration_date": "2019-08-24T14:15:22Z",
  • "external_source_type": "string",
  • "externally_managed": true,
  • "firstname": "string",
  • "jobTitle": "string",
  • "lastname": "string",
  • "ldap_binding_user": true,
  • "location": "string",
  • "managedAppleId": "string",
  • "manager": "string",
  • "mfa": {
    },
  • "middlename": "string",
  • "password": "string",
  • "password_never_expires": true,
  • "passwordless_sudo": true,
  • "phoneNumbers": [
    ],
  • "public_key": "string",
  • "recoveryEmail": {
    },
  • "relationships": [
    ],
  • "restrictedFields": [
    ],
  • "samba_service_user": true,
  • "state": "STAGED",
  • "sudo": true,
  • "suspended": true,
  • "tags": [
    ],
  • "unix_guid": 1,
  • "unix_uid": 1,
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "account_locked": true,
  • "account_locked_date": "string",
  • "activated": true,
  • "addresses": [
    ],
  • "admin": {
    },
  • "allow_public_key": true,
  • "alternateEmail": "string",
  • "attributes": [
    ],
  • "badLoginAttempts": 0,
  • "company": "string",
  • "costCenter": "string",
  • "created": "string",
  • "creationSource": "string",
  • "department": "string",
  • "description": "string",
  • "disableDeviceMaxLoginAttempts": true,
  • "displayname": "string",
  • "email": "string",
  • "employeeIdentifier": "string",
  • "employeeType": "string",
  • "enable_managed_uid": true,
  • "enable_user_portal_multifactor": true,
  • "external_dn": "string",
  • "external_password_expiration_date": "string",
  • "external_source_type": "string",
  • "externally_managed": true,
  • "firstname": "string",
  • "jobTitle": "string",
  • "lastname": "string",
  • "ldap_binding_user": true,
  • "location": "string",
  • "managedAppleId": "string",
  • "manager": "string",
  • "mfa": {
    },
  • "mfaEnrollment": {
    },
  • "middlename": "string",
  • "organization": "string",
  • "password_date": "string",
  • "password_expiration_date": "string",
  • "password_expired": true,
  • "password_never_expires": true,
  • "passwordless_sudo": true,
  • "phoneNumbers": [
    ],
  • "public_key": "string",
  • "recoveryEmail": {
    },
  • "relationships": [
    ],
  • "restrictedFields": [
    ],
  • "samba_service_user": true,
  • "ssh_keys": [
    ],
  • "state": "STAGED",
  • "sudo": true,
  • "suspended": true,
  • "tags": [
    ],
  • "totp_enabled": true,
  • "unix_guid": 1,
  • "unix_uid": 1,
  • "username": "string"
}

Delete a system user

This endpoint allows you to delete a particular system user.

Sample Request

curl -X DELETE https://console.jumpcloud.com/api/systemusers/{UserID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["users"]
Authorizations:
x-api-key
path Parameters
id
required
string
query Parameters
cascade_manager
string

This is an optional flag that can be enabled on the DELETE call, DELETE /systemusers/{id}?cascade_manager=null. This parameter will clear the Manager attribute on all direct reports and then delete the account.

header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request DELETE \
  --url 'https://console.jumpcloud.com/api/systemusers/{id}?cascade_manager=SOME_STRING_VALUE' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "_id": "string",
  • "account_locked": true,
  • "account_locked_date": "string",
  • "activated": true,
  • "addresses": [
    ],
  • "admin": {
    },
  • "allow_public_key": true,
  • "alternateEmail": "string",
  • "attributes": [
    ],
  • "badLoginAttempts": 0,
  • "company": "string",
  • "costCenter": "string",
  • "created": "string",
  • "creationSource": "string",
  • "department": "string",
  • "description": "string",
  • "disableDeviceMaxLoginAttempts": true,
  • "displayname": "string",
  • "email": "string",
  • "employeeIdentifier": "string",
  • "employeeType": "string",
  • "enable_managed_uid": true,
  • "enable_user_portal_multifactor": true,
  • "external_dn": "string",
  • "external_password_expiration_date": "string",
  • "external_source_type": "string",
  • "externally_managed": true,
  • "firstname": "string",
  • "jobTitle": "string",
  • "lastname": "string",
  • "ldap_binding_user": true,
  • "location": "string",
  • "managedAppleId": "string",
  • "manager": "string",
  • "mfa": {
    },
  • "mfaEnrollment": {
    },
  • "middlename": "string",
  • "organization": "string",
  • "password_date": "string",
  • "password_expiration_date": "string",
  • "password_expired": true,
  • "password_never_expires": true,
  • "passwordless_sudo": true,
  • "phoneNumbers": [
    ],
  • "public_key": "string",
  • "recoveryEmail": {
    },
  • "relationships": [
    ],
  • "restrictedFields": [
    ],
  • "samba_service_user": true,
  • "ssh_keys": [
    ],
  • "state": "STAGED",
  • "sudo": true,
  • "suspended": true,
  • "tags": [
    ],
  • "totp_enabled": true,
  • "unix_guid": 1,
  • "unix_uid": 1,
  • "username": "string"
}

List a system user

This endpoint returns a particular System User.

Sample Request

curl -X GET https://console.jumpcloud.com/api/systemusers/{UserID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}'
scopes: ["users","users.readonly"]
Authorizations:
x-api-key
path Parameters
id
required
string
query Parameters
fields
string
Default: ""

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

filter
string

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - starts with

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url 'https://console.jumpcloud.com/api/systemusers/{id}?fields=&filter=SOME_STRING_VALUE' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "_id": "string",
  • "account_locked": true,
  • "account_locked_date": "string",
  • "activated": true,
  • "addresses": [
    ],
  • "admin": {
    },
  • "allow_public_key": true,
  • "alternateEmail": "string",
  • "attributes": [
    ],
  • "badLoginAttempts": 0,
  • "company": "string",
  • "costCenter": "string",
  • "created": "string",
  • "creationSource": "string",
  • "department": "string",
  • "description": "string",
  • "disableDeviceMaxLoginAttempts": true,
  • "displayname": "string",
  • "email": "string",
  • "employeeIdentifier": "string",
  • "employeeType": "string",
  • "enable_managed_uid": true,
  • "enable_user_portal_multifactor": true,
  • "external_dn": "string",
  • "external_password_expiration_date": "string",
  • "external_source_type": "string",
  • "externally_managed": true,
  • "firstname": "string",
  • "jobTitle": "string",
  • "lastname": "string",
  • "ldap_binding_user": true,
  • "location": "string",
  • "managedAppleId": "string",
  • "manager": "string",
  • "mfa": {
    },
  • "mfaEnrollment": {
    },
  • "middlename": "string",
  • "organization": "string",
  • "password_date": "string",
  • "password_expiration_date": "string",
  • "password_expired": true,
  • "password_never_expires": true,
  • "passwordless_sudo": true,
  • "phoneNumbers": [
    ],
  • "public_key": "string",
  • "recoveryEmail": {
    },
  • "relationships": [
    ],
  • "restrictedFields": [
    ],
  • "samba_service_user": true,
  • "ssh_keys": [
    ],
  • "state": "STAGED",
  • "sudo": true,
  • "suspended": true,
  • "tags": [
    ],
  • "totp_enabled": true,
  • "unix_guid": 1,
  • "unix_uid": 1,
  • "username": "string"
}

Update a system user

This endpoint allows you to update a system user.

Sample Request

curl -X PUT https://console.jumpcloud.com/api/systemusers/{UserID} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
    "email":"{email_address}",
    "firstname":"{Name}",
    "lastname":"{Name}"
}'
scopes: ["users"]
Authorizations:
x-api-key
path Parameters
id
required
string
query Parameters
fullValidationDetails
string

This endpoint can take in a query when a client wants all validation errors to be returned with error response for the form field specified, i.e. 'password'

Password validation flag

Use the "password" validation flag to receive details on a possible bad request response Without the password flag, default behavior will be a normal 400 with only a validation string message

?fullValidationDetails=password

Expected Behavior

Clients can expect a list of validation error mappings for the validation query field in the details provided on the response:

{
  "code": 400,
  "message": "Password validation fail",
  "status": "INVALID_ARGUMENT",
  "details": [
      {
        "fieldViolationsList": [{ "field": "password", "description": "passwordHistory" }],
        '@type': 'type.googleapis.com/google.rpc.BadRequest',
      },
  ],
},
header Parameters
x-org-id
string
Default:
Request Body schema: application/json
account_locked
boolean
Array of objects

type, poBox, extendedAddress, streetAddress, locality, region, postalCode, country

allow_public_key
boolean
alternateEmail
string
Array of objects
company
string <= 1024 characters
costCenter
string <= 1024 characters
department
string <= 1024 characters
description
string <= 1024 characters
disableDeviceMaxLoginAttempts
boolean
displayname
string <= 1024 characters
email
string <= 1024 characters
employeeIdentifier
string <= 256 characters

Must be unique per user.

employeeType
string <= 1024 characters
enable_managed_uid
boolean
enable_user_portal_multifactor
boolean
external_dn
string
external_password_expiration_date
string
external_source_type
string
externally_managed
boolean (externallymanagedpropertyinfo)

The externally_managed property has been deprecated. Whenever a user has their externally_managed field modified their restrictedFields property gets populated with the appropriate value, even if it is already set to a value an administrator manually set.

firstname
string <= 1024 characters
jobTitle
string <= 1024 characters
lastname
string <= 1024 characters
ldap_binding_user
boolean
location
string <= 1024 characters
managedAppleId
string <= 1024 characters
manager
string

Relation with another systemuser to identify the last as a manager.

object (mfa)
middlename
string <= 1024 characters
password
string
password_never_expires
boolean
Array of objects
public_key
string
Array of objects
Array of objects (restrictedField)
samba_service_user
boolean
Array of objects (SSHKeyPost)
state
string
Enum: "ACTIVATED" "SUSPENDED"
sudo
boolean
suspended
boolean
tags
Array of strings
unix_guid
integer >= 1
unix_uid
integer >= 1
username
string <= 1024 characters

Responses

Request samples

Content type
application/json
{
  • "account_locked": true,
  • "addresses": [
    ],
  • "allow_public_key": true,
  • "alternateEmail": "string",
  • "attributes": [
    ],
  • "company": "string",
  • "costCenter": "string",
  • "department": "string",
  • "description": "string",
  • "disableDeviceMaxLoginAttempts": true,
  • "displayname": "string",
  • "email": "string",
  • "employeeIdentifier": "string",
  • "employeeType": "string",
  • "enable_managed_uid": true,
  • "enable_user_portal_multifactor": true,
  • "external_dn": "string",
  • "external_password_expiration_date": "string",
  • "external_source_type": "string",
  • "externally_managed": true,
  • "firstname": "string",
  • "jobTitle": "string",
  • "lastname": "string",
  • "ldap_binding_user": true,
  • "location": "string",
  • "managedAppleId": "string",
  • "manager": "string",
  • "mfa": {
    },
  • "middlename": "string",
  • "password": "string",
  • "password_never_expires": true,
  • "phoneNumbers": [
    ],
  • "public_key": "string",
  • "relationships": [
    ],
  • "restrictedFields": [
    ],
  • "samba_service_user": true,
  • "ssh_keys": [
    ],
  • "state": "ACTIVATED",
  • "sudo": true,
  • "suspended": true,
  • "tags": [
    ],
  • "unix_guid": 1,
  • "unix_uid": 1,
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "account_locked": true,
  • "account_locked_date": "string",
  • "activated": true,
  • "addresses": [
    ],
  • "admin": {
    },
  • "allow_public_key": true,
  • "alternateEmail": "string",
  • "attributes": [
    ],
  • "badLoginAttempts": 0,
  • "company": "string",
  • "costCenter": "string",
  • "created": "string",
  • "creationSource": "string",
  • "department": "string",
  • "description": "string",
  • "disableDeviceMaxLoginAttempts": true,
  • "displayname": "string",
  • "email": "string",
  • "employeeIdentifier": "string",
  • "employeeType": "string",
  • "enable_managed_uid": true,
  • "enable_user_portal_multifactor": true,
  • "external_dn": "string",
  • "external_password_expiration_date": "string",
  • "external_source_type": "string",
  • "externally_managed": true,
  • "firstname": "string",
  • "jobTitle": "string",
  • "lastname": "string",
  • "ldap_binding_user": true,
  • "location": "string",
  • "managedAppleId": "string",
  • "manager": "string",
  • "mfa": {
    },
  • "mfaEnrollment": {
    },
  • "middlename": "string",
  • "organization": "string",
  • "password_date": "string",
  • "password_expiration_date": "string",
  • "password_expired": true,
  • "password_never_expires": true,
  • "passwordless_sudo": true,
  • "phoneNumbers": [
    ],
  • "public_key": "string",
  • "recoveryEmail": {
    },
  • "relationships": [
    ],
  • "restrictedFields": [
    ],
  • "samba_service_user": true,
  • "ssh_keys": [
    ],
  • "state": "STAGED",
  • "sudo": true,
  • "suspended": true,
  • "tags": [
    ],
  • "totp_enabled": true,
  • "unix_guid": 1,
  • "unix_uid": 1,
  • "username": "string"
}

Expire a system user's password

This endpoint allows you to expire a user's password.

scopes: ["users"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request POST \
  --url https://console.jumpcloud.com/api/systemusers/{id}/expire \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
"string"

Sync a systemuser's mfa enrollment status

This endpoint allows you to re-sync a user's mfa enrollment status

Sample Request

curl -X POST \
  https://console.jumpcloud.com/api/systemusers/{UserID}/mfasync \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
scopes: ["users"]
Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Request samples

curl --request POST \
  --url https://console.jumpcloud.com/api/systemusers/{id}/mfasync \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "status": "string"
}

Reset a system user's MFA token

This endpoint allows you to reset the TOTP key for a specified system user and put them in an TOTP MFA enrollment period. This will result in the user being prompted to setup TOTP MFA when logging into userportal. Please be aware that if the user does not complete TOTP MFA setup before the exclusionUntil date, they will be locked out of any resources that require TOTP MFA.

Please refer to our Knowledge Base Article on setting up MFA for more information.

Sample Request

curl -X POST \
  https://console.jumpcloud.com/api/systemusers/{UserID}/resetmfa \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{"exclusion": true, "exclusionUntil": "{date-time}"}'
scopes: ["users"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:
Request Body schema: application/json
exclusion
boolean
exclusionDays
number >= 1
exclusionUntil
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "exclusion": true,
  • "exclusionDays": 1,
  • "exclusionUntil": "2019-08-24T14:15:22Z"
}

Response samples

Content type
"string"

List a system user's public SSH keys

This endpoint will return a specific System User's public SSH key.

scopes: ["users","users.readonly"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url https://console.jumpcloud.com/api/systemusers/{id}/sshkeys \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
[
  • {
    }
]

Create a system user's Public SSH Key

This endpoint will create a specific System User's Public SSH Key.

scopes: ["users"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:
Request Body schema: application/json
name
required
string

The name of the SSH key.

public_key
required
string

The Public SSH key.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "public_key": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "create_date": "string",
  • "name": "string",
  • "public_key": "string"
}

Activate System User

This endpoint changes the state of a STAGED user to ACTIVATED.

Email Flag

Use the "email" flag to determine whether or not to send a Welcome or Activation email to the newly activated user. Sending an empty body without the email flag, will send an email with default behavior (see the "Behavior" section below)

{}

Sending email=true flag will send an email with default behavior (see Behavior below)

{ "email": true }

Populated email will override the default behavior and send to the specified email value

{ "email": "example@example.com" }

Sending email=false will suppress sending the email

{ "email": false }

Behavior

Users with a password will be sent a Welcome email to:

  • The address specified in email flag in the request
  • If no email flag, the user's primary email address (default behavior) Users without a password will be sent an Activation email to:
  • The address specified in email flag in the request
  • If no email flag, the user's alternate email address (default behavior)
  • If no alternate email address, the user's primary email address (default behavior)

Sample Request

curl -X POST https://console.jumpcloud.com/api/systemusers/{id}/state/activate \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <api-key>' \
  -d '{ "email": "alternate-activation-email@email.com" }'
scopes: ["users"]
Authorizations:
x-api-key
path Parameters
id
required
string
Request Body schema: application/json
email
object

Responses

Request samples

Content type
application/json
{
  • "email": { }
}

Response samples

Content type
application/json
"string"

Display info about a System User's TOTP enrollment.

This endpoint will return info for a specific System User's TOTP enrollment.

scopes: ["users","users.readonly"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request GET \
  --url https://console.jumpcloud.com/api/systemusers/{id}/totpinfo \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "enrollmentDate": "2019-08-24T14:15:22Z"
}

Unlock a system user

This endpoint allows you to unlock a user's account.

scopes: ["users"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request POST \
  --url https://console.jumpcloud.com/api/systemusers/{id}/unlock \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
"string"

Delete a system user's Public SSH Keys

This endpoint will delete a specific System User's SSH Key.

scopes: ["users"]
Authorizations:
x-api-key
path Parameters
systemuser_id
required
string
id
required
string
header Parameters
x-org-id
string
Default:

Responses

Request samples

curl --request DELETE \
  --url https://console.jumpcloud.com/api/systemusers/{systemuser_id}/sshkeys/{id} \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
"string"

Users

Administrator Password Reset Initiation

This endpoint triggers the sending of a reactivation e-mail to an administrator.

scopes: ["administrators"]
Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Request samples

curl --request GET \
  --url https://console.jumpcloud.com/api/users/reactivate/{id} \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "status": "string"
}

Administrator TOTP Reset Initiation

This endpoint initiates a TOTP reset for an admin. This request does not accept a body.

scopes: ["administrators"]
Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Request samples

curl --request POST \
  --url https://console.jumpcloud.com/api/users/resettotp/{id} \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "status": "string"
}

Update a user

This endpoint allows you to update a user.

scopes: ["administrators"]
Authorizations:
x-api-key
path Parameters
id
required
string
header Parameters
x-org-id
string
Default:
Request Body schema: application/json
apiKeyAllowed
boolean
email
string <email> <= 1024 characters
enableMultiFactor
boolean
firstname
string
growthData
object
lastWhatsNewChecked
string <date>
lastname
string
roleName
string

Responses

Request samples

Content type
application/json
{
  • "apiKeyAllowed": true,
  • "email": "user@example.com",
  • "enableMultiFactor": true,
  • "firstname": "string",
  • "growthData": { },
  • "lastWhatsNewChecked": "2019-08-24",
  • "lastname": "string",
  • "roleName": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "apiKeyAllowed": true,
  • "apiKeyHash": {
    },
  • "apiKeySet": true,
  • "apiKeyUpdatedAt": "2019-08-24T14:15:22Z",
  • "created": "2019-08-24T14:15:22Z",
  • "disableIntroduction": true,
  • "email": "string",
  • "enableMultiFactor": true,
  • "firstname": "string",
  • "growthData": {
    },
  • "lastWhatsNewChecked": "2019-08-24T14:15:22Z",
  • "lastname": "string",
  • "organization": "string",
  • "passwordUpdatedAt": "2019-08-24T14:15:22Z",
  • "provider": "string",
  • "role": "string",
  • "roleName": "string",
  • "sessionCount": 0,
  • "suspended": true,
  • "totpEnrolled": true,
  • "totpUpdatedAt": "2019-08-24T14:15:22Z",
  • "usersTimeZone": "string"
}