Directory Insights API (1.0)

Download OpenAPI specification:Download

Overview

Directory Insights allows you to read event logs, view activity in your directory, and monitor user authentications to the console, RADIUS, LDAP, and SSO apps. Directory Insights analyzes the audit trails that lead to critical events so you know the what, where, when, how, and who of your directory activities.

  • Alert Events: Logs activity related to alerts.
  • Directory Events: Logs activity in the Admin Portal and User Portal, including admin changes in the directory and admin/user authentications to the Admin Portal and User Portal.
  • SAML Events: Logs user authentications to SAML applications.
  • RADIUS Events: Logs user authentications to RADIUS. Used for Wi-Fi and VPNs.
  • Systems Events: Logs user authentications to devices, including agent related events on lockout, password changes, and Full Disk Encryption key updates.
  • LDAP Events: Logs user authentications to LDAP, including LDAP Bind and Search event types.
  • MDM Events: Logs MDM command results.
  • Managed Service Provider Events: Logs activities on the Managed Service Providers (MSP) portal.
  • SaaS App Management Events: Logs activity related to SaaS app management.
  • Software Events: Logs software or plugins detected on the local device.
  • Password Manager Events: Logs activity related to JumpCloud password manager.
  • Object Storage Events: Logs activity related to object storage.
  • Access Management Events: Logs activity related to access management.

Retrieving the MSP Admin API Key

  1. Log into the MTP portal.
  2. Launch any of the child organizations.
  3. Click the icon for the currently logged in MTP Admin user account located on the upper right corner of the page.
  4. Click API Settings.
  5. Copy the MSP Admin API Key that appears in the popup dialog box.

Directory Insights is available in JumpCloud's API, Powershell, and Activity Log. The API uses a single POST endpoint:

https://api.jumpcloud.com/insights/directory/v1/events

Data Retention

JumpCloud stores event logs for 90 days and removes logs older than the retention period. To store data for longer periods of time, JumpCloud offers an AWS Serverless Application that automatically exports Directory Insights events to your S3 Bucket for longer storage options.

Authentication & Authorization

Authentication

Accessing Your API Key

To locate your API Key:

  1. Log in to the JumpCloud Admin Portal.
  2. Click the username drop-down menu located in the top-right of the Admin Portal.
  3. Click API Settings.

API Key Considerations

This API key is associated with the administrator currently logged in. Only administrator roles can access the API. Command runners receive a 403 error.

Important: Do not share this API key, as it grants full access to any data accessible via your JumpCloud admin account.

Recycling or Resetting Your API Key

To revoke access with the current API key, click Generate New API Key in the API settings window. This renders all calls using the previous API key inaccessible.

Example Request

curl -X POST \
  -H 'x-api-key: REPLACE_KEY_VALUE' \
  -H 'Content-Type: application/json' \
  --data '{"service": ["all"], "start_time": "2020-03-03T14:00:00Z"}' \
  --url https://api.jumpcloud.com/insights/directory/v1/events

Managed Service Providers

Managed Service Providers query client organizations and events generated in the Multi-Tenant Portal using an API key from an MSP admin and an organization ID from the client organization.

Example Request with One Organization

curl -X POST -H 'x-api-key: REPLACE_KEY_VALUE' -H 'x-org-id: ADMINISTERED_ORG_ID' -H 'Content-Type: application/json' --data '{"service": ["all"], "start_time": "2020-03-03T14:00:00Z"}' https://api.jumpcloud.com/insights/directory/v1/events

Example Request with Multiple Organizations

Note: There is no limit to the number of org ID's that can be passed in the request.

curl -X POST -H 'x-api-key: REPLACE_KEY_VALUE' -H 'x-org-id: ADMINISTERED_ORG_ID_A' -H 'x-org-id: ADMINISTERED_ORG_ID_B' -H 'x-org-id: ADMINISTERED_ORG_ID_C' -H 'Content-Type: application/json' --data '{"service": ["all"], "start_time": "2020-03-03T14:00:00Z"}' https://api.jumpcloud.com/insights/directory/v1/events

Example to Request Multi-Tenant Portal Events Only

curl -X POST -H 'x-api-key: REPLACE_KEY_VALUE' -H 'x-provider-id: YOUR_PROVIDER_KEY_HERE' -H 'Content-Type: application/json' --data '{"service": ["all"], "start_time": "2020-03-03T14:00:00Z"}' https://api.jumpcloud.com/insights/directory/v1/events

Using the Directory Insights API

JSON POST Request Body

Queries are made by HTTP POST request to the API's /events web context, using curl, Postman, wget, or any other HTTP client.

The two required fields in the JSON body are:

{
    "service": [
        "service name"
    ],
    "start_time": "RFC 3339 date"
}

Valid values for service are:

  • access_management: Logs activity related to access management.
  • alert: Logs from alert services.
  • all: Logs from all services.
  • directory: Logs activity in the Admin Portal and User Portal, including admin changes in the directory and admin/user authentications to the Admin Portal and User Portal.
  • ldap: Logs user authentications to LDAP, including LDAP Bind and Search event types.
  • mdm: Logs MDM command results.
  • password_manager: Logs activity related to JumpCloud password manager.
  • object_storage: Logs activity related to object storage.
  • radius: Logs user authentications to RADIUS, used for Wi-Fi and VPNs.
  • software: Logs application activity when software is added, removed, or changed on a macOS, Windows, or Linux device. Events are logged based on changes to an application version during each device check-in.
  • sso: Logs user authentications to SAML applications.
  • systems: Logs user authentications to MacOS, Windows, and Linux systems, including agent-related events on lockout, password changes, and Full Disk Encryption key updates.

If you specify an invalid or unknown value for "service", the system responds with the list of supported values.

Choose a start time you'd like the service to start searching. Specify an RFC3339-formatted UTC date in the following format: yyyy-mm-ddTHH:mm:ssZ (timezone optional, reference RFC3339 or use Z). For example, RFC3339 = "2020-01-01T14:00:00Z".

You'll be informed about missing or invalid date formats, as well as start dates in the future and end dates before start dates.

Putting these two required fields together, you can search for RADIUS events on or after Jan 1st 2020 2pm UTC with the following JSON HTTP body:

Example

{
    "service": [
        "radius"
    ],
    "start_time": "2020-01-01T14:00:00Z"
}

To put the POST body into a local file for editing, save the JSON structure into a file called simple-query.txt, and execute the following query:

curl -X POST -H 'x-api-key: REPLACE_KEY_VALUE' -d @./simple-query.txt https://api.jumpcloud.com/insights/directory/v1/events

The Directory Insights API returns a JSON array, such as the following:

Example Admin Login Attempt Response

{
    "geoip": {
        "timezone": "America/Denver",
        "country_code2": "US",
        "continent_code": "NA",
        "region_name": "Colorado",
        "region_code": "CO"
    },
    "event_type": "admin_login_attempt",
    "resource": {
        "id": "5ce434e77128503e528e747c",
        "type": "admin",
        "email": "jane.doe@gmail.com"
    },
    "provider": null,
    "success": true,
    "organization": "6ce434e87128303e528e747b",
    "@version": "1",
    "mfa": true,
    "client_ip": "73.203.76.115",
    "id": "5e95d60b05e8907888c4e009",
    "useragent": {
        "patch": "4044",
        "minor": "0",
        "major": "81",
        "os": "Mac OS X",
        "build": "",
        "os_minor": "15",
        "os_major": "10",
        "name": "Chrome",
        "os_name": "Mac OS X",
        "device": "Other"
    },
    "timestamp": "2020-04-14T15:26:03.218Z"
}

Every response with an HTTP 200 status code returns an array of events (possibly an empty array). Each array element is a row describing an event. They include, at a minimum, the exact timestamp that the event occurred. Other fields are variable and can be queried. You can find sample queries further in this document.

Row Size Limit

By default, the system returns a maximum of 1000 rows. You can change the number of rows returned by adding a value for the limit field in the JSON body you send to the service:

Example | Row Limit

{
  "service": [
    "radius"
  ],
  "limit": 2000,
  "start_time": "2020-01-01T14:00:00Z"
}

The maximum number of rows you can request is 10,000 and any nonsensical values for the limit field will cause the system to return the default row count.

HTTP Response Header Metadata

You find information about your query in the HTTP Response headers, including the number of rows returned to you in the results array (result_count), the sort order used (based on the event timestamp), and other fields (limit) which will be discussed later in this document.

HTTP Response Header Metadata Description
X-Result-Count Number of elements in the array returned by the service.
X-Limit Maximum number of rows the service can return in one call.
X-Sort Sort direction of the result array timestamp column.
X-Search_after Token you'll send to the service to get subsequent pages of data. This is explained in the section below.
X-Request-Id Tracing header used to follow a specific query through the system.

Example | Response Header

{
  "X-Result-Count": 1000,
  "X-Limit": 1000,
  "X-Sort": "ASC",
  "X-Search_after": [
    1576181718000,
    "DZrPyW8BNsa9iKWoOm7h"
  ],
  "X-Request-Id": "f5b277fc-7b0b-4c1e-9bee-c5ea1d79302f"
}

Getting All the Pages of Data

It is possible that more rows match your query than are initially returned by the service. To retrieve subsequent pages of data, you must specify the exact same query again, adding specific information from the X-Search_after response header returned to you in your first query.

Example | Response Header

{
  "X-Result-Count": 1000,
  "X-Limit": 1000,
  "X-Sort": "ASC",
  "X-Search_after": [
    1576181718000,
    "DZrPyW8BNsa9iKWoOm7h"
  ],
  "X-Request-Id": "f5b277fc-7b0b-4c1e-9bee-c5ea1d79302f"
}

For example, if the system responds with 1000 events and these HTTP response headers, you will see that the system returned 1000 rows (X-Result-Count) which equaled the limit of the number of rows the service could return (X-Limit). When this happens, (result count == limit) you will need to send more requests to the service to get the remaining pages of matching results.

To get the next page of rows, reissue the query you did the first time, but for this new query, add the search_after section with the value from the X-Search_after header.

Example | Query for Next Page of Results

{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_after": [
    1576181718000,
    "DZrPyW8BNsa9iKWoOm7h"
  ]
}

The system will again respond with the matching events from the second query and a new set of HTTP response headers. To retrieve all of the events matching your query, you must continue comparing the X-Limit and X-Result-Count header values to see if there are still more pages. If so, reissue the query again, but specify the new search_after value. Once the X-Result-Count value is less than X-Limit, you have reached the last page of events data.

Note: The X-Search_after response header value continually changes, which means you will get a different X-Search_after value every time you specify a search. Don't hold on to a X-Search_after value; always parse the specific response you get from the service, then add that value to the search_after JSON property of your query to get the next page of events.

You always need to do the following procedure to get all the rows matching your query:

  1. Send a request.
  2. Check the HTTP status code.
  3. Check to see if there are further rows.
  4. Execute more requests that match your first query but include each search_after value, until the response header X-Result-Count is less than the page X-Limit size.

Note: The header always returns X-Search_after values, even when no further pages of data exist. You must compare X-Result-Count and X-Limit values to know if you're at the last page of data.

Sort

By default, the system responds with events in ascending timestamp order. To override this behavior, add the following to the request body, typically above the search_term section:

Example | Sort

{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "sort": "DESC"
}

The sort field is optional. Nonsensical/missing sort directives cause the system to default to ascending order, silently. The sort directive is not case sensitive.

The sort order used by the system is included with the other HTTP response header metadata: X-Sort:ASC. If the system responds with a value that doesn't match your requested value, it's likely the system has defaulted back to an ASC sort on time.

Selecting Only Specific Fields to Return

By default, the system returns all available fields for each object in the response array. Sometimes, for very large page sizes and result sets, returning less data can improve your download times.

To limit the fields that the system returns, list the fields in an optional fields array. If you specify an empty list or a list containing no known fields, the system will respond with a 400 HTTP status.

Example | Fields

{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "fields": [
    "timestamp",
    "username",
    "client_ip",
    "success"
  ]
}

The previous query returns only the four mentioned fields for each event result in the returned array of events.

End time

Like start_time, the system will optionally accept an end_time value to limit the amount of rows returned to those between the two dates.

Example | End time

{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "end_time": "2020-02-01T14:00:00Z"
}

The previous query returns rows between the two specified dates. The field end_time is not required but if present, must be specified in the search_term section and must come after the value you specify for the start_time field.

Search

The search_term section allows you to query events based on more advanced criteria. You group these criteria with a logical operator of and and or and one or more search terms. To match events with all of a multiple set of criteria, use the and list of terms. If you wish to match events with any of a multiple set of criteria, use the or list of terms.

Valid search terms are any event field returned by the system in the JSON object ("username", "client_ip", "success", etc)

Example Search | AND

{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_term": {
    "and": [
      {
        "username": "root"
      },
      {
        "client_ip": "1.2.3.4"
      }
    ]
  }
}

The previous query returns events with both a username of "root" and a client_ip of "1.2.3.4"

You can add one or more field criteria in the and list. You cannot repeat a field name in the list. The system will return events matching all of the criteria in the list.

There is no system-imposed limit on the number of criteria in the list, however, extremely complex searches may result in HTTP 500 errors.

Example Search | OR

{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_term": {
    "or": [
      {
        "username": "root"
      },
      {
        "client_ip": "1.2.3.4"
      }
    ]
  }
}

The previous query returns any events that have either a username of "root" or a client_ip of "1.2.3.4". To specify multiple values for the same field, enclose them in an array (brackets).

Note: Field values are coerced to lowercase on insert. Use lowercase values in your search_terms.

Search Queries Not Supported A majority of the Directory Insights attributes are searchable except for "changes", "useragent", and "system_timestamp".

Nested Object Event Data You may have noticed that the Directory Insights API returns event data that includes objects in one structure. For example, consider the following event data returned by the API:

{
  "error_message": null,
  "auth_type": "eap",
  "nas_mfa_state": "DISABLED",
  "eap_type": "MSCHAPv2",
  "outer": {
    "error_message": null,
    "eap_type": "PEAP",
    "username": "zezeye21"
  },
  "mfa": false,
  "mfa_meta": {
    "type": "none"
  },
  "success": true,
  "organization": "5dc058bc3f53f95e3972f03f",
  "client_ip": "209.235.170.66",
  "id": "ED0ED2C3-0524-3263-BE5B-68C02B70986E",
  "username": "zezeye21",
  "timestamp": "2019-12-12T20:15:15Z"
}

Queries (and field return lists) accept any of the top-level field names (such as "client_ip"and "username") by default.

In the event above, you can see event data named "outer" that itself is a list of fields. To query one of these sub-fields, use a "dot" notation, specifying the parent (outer) field name, and the child field name. For example, specify the query:

{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_term": {
    "and": [
      {
        "outer.eap_type": "PEAP"
      }
    ]
  }
}

For the query above, the service returns only events with an "outer" field list containing an "eap_type" value of "PEAP".

Note: You may use this parent-child dot notation in and/or queries, field projection lists and anywhere event fields can be specified.

Advanced Search: List Values

Instead of searching for a single value, you can also specify a list of values to search in the and and or criteria.

Example Advanced Search | AND

{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_term": {
    "and": [
      {
        "username": [
          "root",
          "admin"
        ]
      }
    ]
  }
}

The previous example returns any events that have a username of either "root" or "admin".

Example Advanced Search | OR

{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_term": {
    "or": [
      {
        "username": [
          "root",
          "admin"
        ]
      },
      {
        "client_ip": [
          "1.2.3.4",
          "2.3.4.5"
        ]
      }
    ]
  }
}

The previous example returns all events that have EITHER:

  • A username of "root" or "admin".
  • A client_ip of "1.2.3.4" or "2.3.4.5".

If you change the query to "and", the system would match documents with BOTH those criteria.

Note: JSON does not allow a term to be repeated. For example, you cannot request different values for the same field as shown in the example below:

{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_term": {
    "or": [
      {
        "username": "root"
      },
      {
        "username": "admin"
      }
    ]
  }
}

Advanced Search: Compound Logic

The search_term section allows complex queries using compound logic with and and or logical operators. All of the content of both and and or should be comma-separated JSON objects, enclosed in a JSON array [].

Example | Search for Failed Authentications of Paul Where (initiated_by.username = paul OR username = paul) AND success = false

{
  "service": [
    "radius"
  ],
  "start_time": "2020-01-01T14:00:00Z",
  "search_term": {
    "and": [
      {
        "success": "false"
      },
      {
        "or": [
          {
            "initiated_by.username": "paul"
          },
          {
            "username": "paul"
          }
        ]
      }
    ]
  }
}

Schemas

Alert Attributes

Field Type Example Description
id uuid 5c8fcfe0e7eb500001c71062 Unique id for the event.
event_type string alert_created Event type.
timestamp RFC3339 Timestamp 2019-03-04T18:08:26Z Timestamp of when the event occurred (UTC).
service string alerts Service that the event originated from.
organization keyword 5a2af2a82cf2b0010053ea41 Organization that the user belongs to.
changes Nested objects [{"field": "folder name", "from": "", "to": "NB folder"}] List of changes made in the request. You cannot search on the contents of this field.
correlation object {"id": "rule_id"} Details for a background process or parent event that can be used to correlate related events.
category string System/Directory/.. Category of alert
geoip object {"geoip": {"timezone": "America/Los_Angeles", "continent_code": "NA", "region_code": "OR", "country_code": "US", "region_name": "Oregon"}} Geo IP information for the IP address that made the request.
initiated_by object [{"field": "Status", "from": "Open", "to": "Acknowledged"},{"field": "Remark", "from": "", "to": "Acked alert"}] Object that describes who initiated the request.
client_ip string 10.1.2.3 IP address the request came from.
success boolean TRUE Denotes whether a alert attempt was successful.
severity string "Medium" Severity of alert.
username string john.doe Username provided for the alert service call.
resource object { "id": "alert_object_id", "context": "alert-context-json", "source_id": "device_id or user_id", "source_type": "device or user", "reference_id": "alert_reference_id"} Object that describes the alert resource.

Directory Attributes

Field Type Example Description
id uuid 30b03bc3-be76-4919-b341-f9b271a5777e Unique ID for the event.
correlation object {"id": "62d5c9dd98b6a90001312dff", "type": "user_import"} Details for a background process or parent event that can be used to correlate related events.
event_type string systemuser_update Event type.
timestamp RFC3339 Timestamp 2019-03-04T18:08:26Z Timestamp of when the event occurred (UTC).
resource object {"type": "systemuser", "id": "5c86b7149fdce00001d38014", "username": "testexample", "recipient_email": "testexample@example.com", "email_type": "company", "name": "displayName"} Resource that changed or attempted the login.
system_group object {"type": "system_group","object_id": "61129b4c8afaf1e9da9b83e4","name": "My Device Group"} Object that contains the closest device/system group involved in the event.
organization keyword 5a2af2a82cf2b0010053ea41 Organization that the user belongs to.
changes Nested objects [{"field": "lastname", "from": "0c7ee32b-345e-473e-a450-ebc7dddb0566", "to": "48163dd3-e9cf-44d3-b48a-438a0177e308"}] List of changes made in the request. You cannot search on the contents of this field.
initiated_by object {"user_id": "6239f8de32a30d44d6243a64", "administrator": true, "id": "5845d8f9c4894c85596c54f3", "type": "admin", "email": "user1@domain.com", "source": "jumpcloud:scim", "source_metadata": {"name": "okta"}} Object that describes who initiated the request.
association object {"type": "admin", "id": "5c86b6cf9fdce00001d3800c", "email": "user1@domain.com"} Object that describes a change in association, such as adding a user to a group.
client_ip string 10.1.2.3 IP address that the request came from.
useragent object {"useragent": {"os": "Fedora", "minor": "0", "major": "71", "build": "", "name": "Firefox", "os_name": "Fedora", "device": "Other"} User agent information for the browser that submitted the request. You cannot search on the contents of this field.
auth_method string session Session = console, api-key = api-key
success boolean true Denotes whether a login attempt was successful.
mfa boolean true Denotes whether MFA was used on an authentication attempt.
mfa_meta object {"type": "duo"} Object that contains metadata around MFA authentication such as the type of MFA.
geoip object {"geoip": {"timezone": "America/Los_Angeles", "continent_code": "NA", "region_code": "OR", "country_code": "US", "region_name": "Oregon"}} Geo IP information for the IP address that made the request.
provider string 5c86b6cf9fdce00001d3800c The org ID of the provider if the org is a provider org.
service string directory Service that the event originated from.
auth_context object {"auth_methods": {"totp": {"success": true}, "webauthn": {"success": false}, "duo": {"success": false}, "password": {"success": true}}, "system": {"hostname": "my-host", "id": "5e90795a9de53959cf505121", "displayName": "My Computer", "os": "Microsoft Windows 10 Pro", "version": "10.0.18362"}, "policies_applied": [{"name": "policyA", "id": "5e90795a9de53959cf505111"}, {"name": "policyB", "id": "5e90795a9de53959cf505112"}]} Object for authentication context including factors used, device information if cert was present, and policies that were applied.
application object {"id": "5c86b7469fdce00001d38016", "name": "aws"} Information for the application that the event was initiated for.
idm_client_id string 62ebd659c306695de4eb9c75 The client ID for the Identity Management integration
error_message string Pug: render error on line 1 Error details.
message_chain object {"response_code": "200", "response_message": "Application successfully activated", "message_details": "OK"} Results detail for each event
@version integer 1 The schema version for the document object.
system object {"hostname": "ADE6B6", "displayName": "WIN10.AVAILABLE.APAC", "id": "611f642091129216830cc2c6", "type": "system"} The object that describes the system.
target_resource object {"type": "admin_portal"} The object that describes the target_resource.

Password Manager Attributes

Field Type Example Description
id uuid 30b03bc3-be76-4919-b341-f9b271a5777a Unique id for the event.
event_type string passwordmanager_enable Event type.
timestamp RFC3339 Timestamp 2019-03-04T18:08:26Z Timestamp of when the event occurred (UTC).
service string password_manager Service that the event originated from.
organization keyword 5a2af2a82cf2b0010053ea41 Organization that the user belongs to.
changes Nested objects [{"field": "folder name", "from": "", "to": "NB folder"}] List of changes made in the request. You cannot search on the contents of this field.
initiated_by object {"id": "60d4d8f72c6b9226e875781a", "type": "admin", "email": "exampleuser@example.com", "source": "system"} Object that describes who initiated the request.
association object {"type": "admin", "id": "5c86b6cf9fdce00001d3800c", "email": "user1@domain.com"} Object that describes a change in association, such as adding a user to a folder.
client_ip string 10.1.2.3 IP address the request came from.
user_agent object {"patch": "4638", "os": "Mac OS X", "major": "95", "minor": "0", "build": "", "os_minor": "15", "os_major": "10", "name": "Chrome", "os_name": "Mac OS X", "device": "Other"} User agent information for the browser that submitted the request.
success boolean TRUE Denotes whether the event was successful or failed.
geoip object {"country_code": "US", "timezone": "America/New_York", "latitude": 33.6992, "continent_code": "NA", "region_name": "Georgia", "region_code": "GA", "longitude": -84.7478} Geo IP information for the IP address that made the request.
provider uuid 5c86b6cf9fdce00001d3800c The org ID of the provider, if the org is a provider org.
error_message string This user can't be updated because it's the last folder admin Error details.
@version string 1 The schema version for the document object.

MTP/MSP Events

Field Type Example Description
service string directory The service the event originated from.
event_type string admin_update Examples of MTP events, such as admin_password_reset_request, admin_login_attempt, admin_lockout, admin_update, admin_create, admin_unsuspend, admin_suspended, admin_password_change, organization_create, organization_update, or provider_update.
client_ip string 34.214.221.231 The IP address the request came from.
resource object {"type": "admin", "id": "6154d26a4dea2b7ec773b133", "email": "exampleadmin@example.com"} Resource that was changed.
changes list [{"field": "lastname", "from": "", "to": "Edited"}] List of changes made from the old record to the new record. You cannot search on the contents of this field.
timestamp RFC3339 Timestamp 2021-10-22T17:38:53.650Z Timestamp of when the event occurred (UTC).
provider string 5e160715b7782848e073301e The org ID of the provider if the org is a provider.
geoip object {"geoip": {"timezone": "America/Los_Angeles", "continent_code": "NA", "region_code": "OR", "country_code": "US", "region_name": "Oregon", "latitude": "45.8491", "longitude": "-119.7143"}} Geo IP information for the IP address that made the request.
id string 5c8fcfe0e7eb500001c71062 Unique ID for the event.
useragent object {"useragent": {"patch": "4472", "os": "Mac OS X", "minor": "0", "major": "91", "build": "", "os_minor": "15", "os_major": "10", "name": "Chrome", "os_name": "Mac OS X", "device": "Other"}} User agent information for the browser that submitted the request. You cannot search on the contents of this field.
@version integer 1 The schema version for the document object.
initiated_by object {"type": "admin", "id": "60dca2e6c6b18a68cc4093dc", "provider": "5e160715b7782848e073301e", "email": "exampleadmin@example.com"} Object that describes who initiated the request.
auth_method string session Session == console and api-key == api-key.
organization string 5c86b6cf9fdce00001d3800b The org associated with the event if it is present on the user, system user, or on the request. Otherwise, the value will be null.
mfa boolean true If true, MFA was used on the authentication attempt. If false, it was not.

SSO Attributes

Field Type Example Description
id uuid 30b03bc3-be76-4919-b341-f9b271a5777e Unique ID for the event.
event_type string sso_auth Event type. Note: For SSO, JumpCloud only supports sso_auth at this time.
timestamp RFC3339 Timestamp 2019-03-04T18:08:26Z Timestamp of when the event occurred (UTC).
initiated_by object {"type": "systemuser", "id": "5c86b7149fdce00001d38014", "username": "testexample"} User who initiated the auth attempt.
organization keyword 5a2af2a82cf2b0010053ea41 Organization that the user belongs to.
application object {"display_label": "Zendesk SSO", "id": "5c86b7469fdce00001d38016", "name": "zendesk", "sso_url": "https://sso.jumpcloud.com/saml2/zendesk"} Information for the application that the sso_auth was initiated for.
client_ip string 10.1.2.3 IP address the request came from.
useragent object {"useragent": {"os": "Fedora", "minor": "0", "major": "71", "build": "", "name": "Firefox", "os_name": "Fedora", "device": "Other"}} User agent information for the browser that submitted the request.
geoip object {"geoip": {"timezone": "America/Los_Angeles", "continent_code": "NA", "region_code": "OR", "country_code": "US", "region_name": "Oregon"}} Geo IP information for the IP address that made the request.
idp_initiated bool TRUE Returns true if the request was initiated from the Identity Provider (JumpCloud). Returns false if the auth was initiated from the service provider.
service string sso Which service the event originated from.
@version integer 1 The schema version for the document object.

RADIUS Attributes

Name Type Example Description
id string 077ED0A8-1B5F-3EA3-8AAC-E3999451A46D Unique ID for the event.
event_type string radius_auth Event type.
nas_mfa_state string disabled, enabled, required, always. Disabled: No MFA required. Enabled: MFA is required if the user is configured for MFA. Required: MFA is required unless the user is excluded and not configured for MFA. Always: MFA always required.
auth_type string pap Authentication type.
eap_type string MSCHAPv2 EAP type.
client_ip string 192.168.0.1 IP address the request came from.
Geoip object {"geoip": {"timezone": "America/Los_Angeles", "continent_code": "NA", "region_code": "OR", "country_code": "US", "region_name": "Oregon"}} Geo IP information for the IP address that made the request.
success boolean true or false Indicates whether the authentication succeeded.
username string john.doe Username provided for the auth attempt.
organization string 5530392c3e2ab2b60c000047 Org associated with the username and NAS.
timestamp RFC3339 Timestamp 2019-03-04T18:08:26Z Timestamp of when the event occurred (UTC).
error_message string "pap: Crypt digest does not match \"known good\" digest"
mfa boolean true or false Whether MFA was supplied.
mfa_meta string {"type":"totp"} Information on the type of MFA.
outer object {"outer": {"eap_type": "PEAP", "error_message": null, "username": "fguo"}} Object for outer.
outer:eap_type string peap Outer eap type.
outer:username string steve Outer username.
outer:error_message string "eap_peap: The users session was previously rejected: returning reject (again.)", "eap: Failed continuing EAP PEAP (25) session. EAP sub-module failed" Outer error message.
service string radius Which service the event originated from.
initiated_by object {"id": "5845d8f9c4894c85596c54f3", "type": "admin", "email": "user1@domain.com"} Object that describes who initiated the request.
@version integer 1 The schema version for the document object.

Systems Attributes

Name Type Example Description
timestamp RFC3339 Timestamp 2019-03-04T18:08:26Z Timestamp of when the event occurred (UTC).
system_timestamp RFC3339 Timestamp 2019-04-09T05:01:18+09:30 Local system time.
id string 5c8fcfe0e7eb500001c71062 Unique ID for the event.
event_type string user_login Event type.
organization string 5c86b6cf9fdce00001d3800b Org associated with the event.
system object {"id": "5c86b7149fdce00001d38014", "hostname": "my-host", "displayName": "My System"} Object that describes the system.
message string User vagrant logged in from 10.0.2.2, process name: sshd Log message associated with a login attempt.
client_ip string 10.1.2.3 IP address the request came from.
src_ip string 10.0.2.2 IP address the login request came from.
username string vagrant Username provided for the auth attempt.
process_name string sshd Process that initiated a login attempt.
success bool TRUE Whether a system authentication succeeded.
provider string 5c86b6cf9fdce00001d3800b The org ID of the provider if the org is a provider.
resource object {"type": "systemuser", "id": "5c86b7149fdce00001d38014", "username": "testexample"} Object for the resource changed.
changes list [{"field": "password"}] List of changes made in the request. You cannot search on the contents of this field.
initiated_by object {"type": "systemuser", "id": "5c86b6cf9fdce00001d3800c", "username": "testuser"} Object that describes who initiated the request.
service string systems Which service the event originated from.
windows_meta object {"elevated": true, "logon_type": "5"} Information about Windows authentications including whether the login had elevated privileges and the logon type. Logon types: 2 Interactive, 3 Network, 4 Batch, 5 Service, 7 Unlock, 8 NetworkCleartext, 9 NewCredentials, 10 RemoteInteractive, 11 CachedInteractive.
@version integer 1 The schema version for the document object.

Software Attributes

Name Type Example Description
id string 60ca54965f723c17b5ee75f5 Unique ID for the event.
event_type string software_add Type of software event.
service string software Name of the feature that emits events.
timestamp RFC3339 Timestamp 2019-03-04T18:08:26Z Timestamp of when the event occurred (UTC).
provider string 5c8fcfe0e7eb500001c71062 Unique ID for the provider.
organization string 606b42c6c627474cf6ee1c6f Unique ID for the organization.
system object {"id": "5ce434e77128503e528e747c", "type": "system"} Object that describes the system program.
application object {"name": "Google Chrome", "version": "96.1", "path": "/path/to/chrome", "publisher": "Google", "uninstall_string": "C:\\Users\\cpointe\\AppData\\Local\\Google\\"} The software application being added, changed or removed.
changes list [{"field": "version", "from": "96.0", "to": "96.1"}] List of changes made from the old record to the new record. You cannot search on the contents of this field.
resource object {"id": "5ce434e77128503e528e747c", "type": "system"} Object that describes the software resource.
app_management_source string JumpCloud App Catalog The JumpCloud method of configuring and installing the application.
@version integer 1 The schema version for the document object.

LDAP Attributes

Name Type Example Description
timestamp RFC3339 Timestamp 2019-03-04T18:08:26Z Timestamp of when the event occurred (UTC).
connection_id string UhKgFeYIvbsh4so/f8z7xUnH0rDLk5Ph1n6XQnT08ds= Unique id for every LDAP connection.
operation_number integer 0 All operation requests and operation result pairs are given incremental operation numbers beginning with operation_number=0 to identify the distinct operations being performed.
event_type string ldap_bind The type of LDAP event: bind or search.
dn string uid=adminR,ou=Users,o=57600aea6b8a769c6cef11ed,dc=jumpcloud,dc=com Distinguished name (DN) provided for authentication. In this example we are authing user adminR in org. 57600aea6b8a769c6cef11ed
auth_method string simple, sasl, or anonymous Authentication method. The values are: 128 = simple, 163 = sasl, 0 = anonymous.
mech string simple The authentication method used. Either simple or SASL (JumpCloud does not support SASL at this time).
start_tls boolean false The starttls protocol that was used to open the LDAP connection.
tls_established boolean false The LDAPS protocol that was used to open the LDAP connection.
username string john.doe Username provided for the auth attempt.
organization string 5530392c3e2ab2b60c000047 Org associated with the username and NAS.
success boolean true or false Whether the authentication succeeded.
error_code integer 10 Result code.
error_message string invalid DN Optional error message.
oid string 1.3.6.1.4.1.1466.20037 LDAP object identifier.
base string ou=Users,o=55ddd95d90426433661ae1e0,dc=jumpcloud,dc=com The base of the subtree in which the search is to be constrained.
scope integer 2 The search scope. This specifies the portion of the target subtree that should be considered. The values are: base, only return the specified entry. If singleLevel (1) only the immediate children of the entry are considered.
deref integer 0 The alias dereferencing behavior, which indicates how the server should treat any aliases encountered while processing the search.
filter string (&(objectClass=sambaDomain)(sambaDomainName=workgroup)) The filter criteria for the search with the scope.
attr string sambaDomainName sambaNextRid A set of attributes to be returned to the client.
number_of_results integer 1 Number of rows returned from the search.
service string ldap Service the event originated from.
initiated_by object {"id": "5845d8f9c4894c85596c54f3", "type": "admin", "email": "user1@domain.com"} Object that describes who initiated the request.
auth_meta object {"auth_methods": {"totp": {"success": true}, "password": {"success": true}, "jumpcloud_protect": {"success": false}}, "jumpcloud_protect_device": {"id": "5eda66d5bd5b135d72390f06", "make": "Apple", "model": "iPhone 11", "os": "iOS", "os_version": "14.01", "app_version": "1.0345", "username": "paul", "user_id": "606cce8a3d9dcc601774caed", "ip": "174.16.38.486"}} Object for authentication context including factors used, device information if cert was present, push device information if JumpCloud Protect was a factor, and policies that were applied.
@version integer 1 The schema version for the document object.

MDM Attributes

Name Type Example Description
id string 5c8fcfe0e7eb500001c71062 Unique ID for the event.
timestamp RFC3339 Timestamp 2019-03-04T18:08:26Z Timestamp of when the event occurred (UTC).
organization string 5c86b6cf9fdce00001d3800b Org associated with the event.
event_type string mdm_command_result The type of MDM event.
mdm_type string apple The type of MDM service.
device_object_id string 5ebeb092658f7304f48e2d84 Unique ID for the device.
device_manager_object_id string 5e95d0a128b4f8666ef26b87 Unique ID for the device manager.
windows_device_uuid string D123IS95E75C77459910B18EDB5470FG Unique ID for the windows device.
initiated_by object {"email": "user1@domain.com"} Object containing info of the entity that triggered the event.
command_uuid string a0325748-b432-42f6-b789-50b3924d64a4 Unique ID for the command.
request_type string RestartDevice The type of command.
command object {"request_type": "RestartDevice"} The executed command.
status string Acknowledged The command result: Acknowledged, Error, CommandFormatError, and Idle.
error_chain object [{"error_code": INT, "error_domain": STRING, "localized_description": STRING, "us_english_description": STRING}] Raw error details as reported by the MDM device.
success boolean true or false Reports whether the mdm operation succeeded or not.
result string "successful enrollment of device" Description of the end result of the event
geoip object {"country_code": "US", "timezone": "America/New_York", "latitude": 33.6992, "continent_code": "NA", "region_name": "Georgia", "region_code": "GA", "longitude": -84.7478} Geo IP information for the IP address that made the request.
@version integer 1 The schema version for the document object.
service string mdm Service the event originated from.

Object Storage Attributes

Name Type Example Description
id string 5c8fcfe0e7eb500001c71062 Unique ID for the event.
timestamp RFC3339 Timestamp 2019-03-04T18:08:26Z Timestamp of when the event occurred (UTC).
event_type string object_storage_create Type of object storage event.
service string object_storage Service the event originated from.
result string Success The result of the creation of the object.
organization string 5530392c3e2ab2b60c000047 Unique ID for the organization.
referrer_object_id string 5e95d0a128b4f8666ef26b87 Unique ID for the referrer.
referrer_type string SOFTWARE_APP The type of referrer.
object_storage_item_object_id string 5e95d0a128b4f8666ef26b87 Unique ID for the object storage item.
object_storage_item_version_object_id string 5e95d0a128b4f8666ef26b87 Unique ID for the object storage item version.
object_storage_item_version_name string GoogleChrome.pkg Name of the object storage item.
object_storage_item_version_size integer 178398259 Size of the object storage item's version in bytes.
object_storage_item_version_sha_256_sum string 65d860160bdc9b98abf72407e14ca40b609417de7939897d3b58d55787aaef69 Object storage item version's SHA-256 sum.
total_software_item_count integer 164 Total count of object storage items with a SOFTWARE_APP referrer type for the organization.
total_space_used integer 234523452323 Total sum of object storage items.
system_object_id string 5e95d0a128b4f8666ef26b87 Unique ID for the system associated with the request.
@version integer 1 The schema version for the document object.

SaaS App Management Attributes

Field Type Example Description
id uuid 5c8fcfe0e7eb500001c71062 Unique ID for the event.
event_type string saas_management_enable Type of SaaS Management event.
timestamp RFC3339 Timestamp 2019-03-04T18:08:26Z Timestamp of when the event occurred (UTC).
service string saas_app_management Service that the event originated from.
organization keyword 5a2af2a82cf2b0010053ea41 Organization that the user belongs to.
changes Nested objects [{"field": "status", "from": "UNAPPROVED", "to": "APPROVED"}] List of changes made in the request. You cannot search on the contents of this field.
geoip object {"geoip": {"timezone": "America/Los_Angeles", "continent_code": "NA", "region_code": "OR", "country_code": "US", "region_name": "Oregon"}} Geo IP information for the IP address that made the request.
initiated_by object {"type": "systemuser", "id": "5c86b6cf9fdce00001d3800c", "username": "testuser"} Object that describes who initiated the request.
client_ip string 10.1.2.3 IP address the request came from.
username string john.doe Username provided for the event.
resource object {"application_id": "jumpcloud", "application_name": "JumpCloud", "application_category": "Identity and Access"} Object that describes the SaaS Management event resource.
detail string SaaS Management application reviewed. Log message associated with an alert event.
@version integer 1 The schema version for the document object.

Access Management Attributes

Field Type Example Description
id uuid 30b03bc3-be76-4919-b341-f9b271a5777a Unique id for the event.
event_type string access_management_access_request Event type.
timestamp RFC3339 Timestamp 2019-03-04T18:08:26Z Timestamp of when the event occurred (UTC).
service string access_management Service that the event originated from.
pid string b3a67f24-5284-4f08-b421-1250bce477f0 Partner ID of the MSP.
organization keyword 5a2af2a82cf2b0010053ea41 Organization that the user belongs to.
access_request_id string 6731f04942e10f0001dd6013 Access request ID.
changes Nested objects [{"field": "folder name", "from": "", "to": "NB folder"}] List of changes made in the request. You cannot search on the contents of this field.
resource object {"type": "systemuser", "id": "5c86b7149fdce00001d38014", "name": "testexample"} Resource that the event originated on.
workflow object {"type": "access-workflow", "id": "5c86b7149fdce00001d38014", "name": "testexample", "desc": "description of the workflow"} Workflow object with id name type and description.
initiated_by object {"id": "60d4d8f72c6b9226e875781a", "type": "admin", "email": "exampleadmin@example.com", "source": "system"} Object that describes who initiated the request.
association object {"type": "admin", "id": "5c86b6cf9fdce00001d3800c", "email": "user1@domain.com"} Object that describes a change in association, such as adding a user to a folder.
client_ip string 10.1.2.3 IP address the request came from.
user_agent object {"patch": "4638", "os": "Mac OS X", "major": "95", "minor": "0", "build": "", "os_minor": "15", "os_major": "10", "name": "Chrome", "os_name": "Mac OS X", "device": "Other"} User agent information for the browser that submitted the request.
success boolean TRUE Denotes whether the event was successful or failed.
geoip object {"country_code": "US", "timezone": "America/New_York", "latitude": 33.6992, "continent_code": "NA", "region_name": "Georgia", "region_code": "GA", "longitude": -84.7478} Geo IP information for the IP address that made the request.
provider uuid 5c86b6cf9fdce00001d3800c The org ID of the provider, if the org is a provider org.
error_message string This user can't be updated because it's the last folder admin Error details.
@version string 1 The schema version for the document object.

Event Types

Directory - Object Events

Event Description
application_create SAML application is created.
application_delete SAML application is deleted.
application_update SAML application is modified.
association_change Resource bound/unbound to a group.
group_create Group is created.
group_delete Group is deleted.
group_update Group is modified.
integrationattribute_include Attribute mapping is created.
integrationattribute_exclude Attribute mapping is deleted.
invoice_download Admin downloads org invoice
notification_delete Notification is closed.
organization_create Organization is created.
organization_update An organization is updated.
system_create System is created.
system_delete System is deleted.
system_update System is updated.
radiusserver_create RADIUS server is created.
radiusserver_delete RADIUS server is deleted.
radiusserver_update RADIUS server is updated.
user_group_admin_grant Administrator access granted.
user_group_admin_revoke Administrator access revoked.

Directory - User and Admin Events

Event Description
admin_create Admin is created.
admin_delete Admin is deleted.
admin_login_attempt Admin logs in success / failure.
admin_password_reset_request Admin requests to reset their password.
admin_update An admin account is updated.
admin_totp_start_enrollment An admin's TOTP enrollment is initiated.
admin_totp_finish_enrollment An admin's TOTP enrollment is finished.
admin_totp_disable An admin's TOTP requirement is disabled.
totp_start_enrollment A user's TOTP enrollment is initiated.
totp_finish_enrollment A user's TOTP enrollment is finished.
totp_delete_enrollment A user's TOTP enrollment is deleted.
user_create A user account is created.
user_delete A user account is deleted.
user_lockout A user account is locked out.
user_login_attempt A user attempted to authenticate to user portal.
user_mfa_exclusion_expired User's MFA enrollment expires.
user_password_expired User's password expires.
user_password_reset_request User requests to change their password.
user_password_warning_email Password warning email is sent to user.
user_update A user account is updated.
user_password_change A user's password changed.
user_activated A user account is activated.
user_activation_email Activation email is sent to user.
user_password_set A user account moves out of pending status.
user_unlocked A user account is unlocked.
user_suspended A user account is suspended.
user_unsuspended A user account is unsuspended.
user_activation_schedule_create A scheduled job to activate a user account is created.
user_activation_schedule_delete A scheduled job to activate a user account is deleted.
user_suspension_schedule_create A scheduled job to suspend a user account is created.
user_suspension_schedule_delete A scheduled job to suspend a user account is deleted.
admin_password_change An admin's password changed.
user_create_provision User created in external application.
user_update_provision User updated in external application.
user_delete_provision User deleted in external application.
user_admin_granted Admin granted user admin sudo privileges on device(s).
user_admin_revoked Admin revoked user admin sudo privileges on device(s).

Directory - Command and Policy Events

Event Description
command_create Command is created.
command_delete Command is deleted.
command_run Command runs.
command_update Command is modified.
commandresult_delete Command result is deleted.
file_create File is uploaded in a command.
file_delete File is deleted in a command.
file_update File is changed in a command.
policy_create Policy is created.
policy_delete Policy is deleted.
policy_update Policy is modified.
authnpolicy_create Conditional access policy created.
authnpolicy_delete Conditional access policy deleted.
authpolicy_update Conditional access policy updated.
iplist_create IP address list created.
iplist_delete IP address list deleted.
iplist_update IP address list updated.

Directory - Integrations

Event Description
activedirectory_create Active Directory instance created.
activedirectory_delete Active Directory instance deleted.
idsource_create AD Bridge V1 created.
idsource_delete AD Bridge v1 deleted.
idsource_update AD Bridge V1 updated.
sambadomain_create Enabling Samba for LDAP directory.
sambadomain_delete Disabling/removing Samba for LDAP directory.
sambadomain_update Updating Samba configuration.
workday_create Workday directory created.
workday_delete Workday directory deleted.
workday_update Workday directory updated.
integration_activate SCIM integration activated.
integration_deactivate SCIM integration deactivated.
gsuite_directory_create Google Workspace directory created.
gsuite_directory_update Google Workspace directory updated.
gsuite_directory_delete Google Workspace directory deleted.
o365_directory_create M365 directory created.
o365_directory_update M365 directory updated.
o365_directory_delete M365 directory deleted.
integration_domain_add Add domain in o365 or Google Workspace.
integration_domain_delete Delete domain in o365 or Google Workspace.
integration_default_domain_add Add default domain in o365 or Google Workspace.
integration_default_domain_update Update default domain in o365 or Google Workspace.
integration_default_domain_delete Delete default domain in o365 or Google Workspace.

Directory - MTP/MSP Events

MTP Events Overview

The MTP (multi-tenant portal) tracks administrator actions as events within the MTP portal and allows MSPs (managed service providers) to search for events across their managed organizations. Reports can be created that explain how your administrators access and use the multi-tenant portal and can also be used to view all events across MSP client organizations centrally. Use the Directory Insights API to analyze the event data in these reports and to create custom solutions tailored to your organization's specific needs.

The availability of the events data is governed by the JumpCloud data retention policies. For more information, see data retention policies.

What are the MTP activity events?

MTP provides the following types of events:

Event Description
admin_unsuspend Created when admin unsuspends an admin.
admin_create Created when admin creates an admin.
admin_delete Created when admin deletes a user or bulk deletes users.
admin_lockout Created when an admin has multiple login failures into MTP portal.
admin_login_attempt Created when an admin logs into the MTP portal or admin launches an child org.
admin_password_reset_request Created when an admin resets their password.
admin_suspended Created when admin suspends an admin.
admin_update Created when admin enables/disables TOTP, changes contact info, role for an admin or admin updates an admin.
organization_create Created when an admin creates an organization.
organization_update Created when an organization is updated.
provider_update Created when admin changes billing info.
mtp_download_invoice Created when an admin downloads an invoice.
msp_ticket_create Created when a ticket is created for a partner integration (e.g. Autotask, ConnectWise) successfully or unsuccessfully.
connectwise_integration_create Created when an admin creates a ConnectWise integration.
connectwise_integration_update Created when an admin updates a ConnectWise integration.
connectwise_integration_delete Created when an admin deletes a ConnectWise integartion.
connectwise_billing_mapping_create Created when an admin creates a ConnectWise billing mapping.
connectwise_billing_mapping_update Created when an admin updates a ConnectWise billing mapping.
connectwise_billing_mapping_delete Created when an admin deletes a ConnectWise billing mapping.
connectwise_company_mapping_create Created when an admin creates a ConnectWise company mapping.
connectwise_company_mapping_update Created when an admin updates a ConnectWise company mapping.
connectwise_company_mapping_delete Created when an admin deletes a ConnectWise company mapping.
connectwise_settings_update Created when an admin updates ConnectWise settings.
autotask_integration_create Created when an admin creates an Autotask integration.
autotask_integration_update Created when an admin updates an Autotask integration.
autotask_integration_delete Created when an admin deletes an Autotask integration.
autotask_billing_mapping_create Created when an admin creates an Autotask billing mapping.
autotask_billing_mapping_update Created when an admin updates an Autotask billing mapping.
autotask_billing_mapping_delete Created when an admin deletes an Autotask billing mapping.
autotask_company_mapping_create Created when an admin creates an Autotask company mapping.
autotask_company_mapping_update Created when an admin updates an Autotask company mapping.
autotask_company_mapping_delete Created when an admin deletes an Autotask company mapping.
autotask_settings_update Created when an admin updates Autotask settings.
syncro_integration_create Created when an admin creates a Syncro integration.
syncro_integration_update Created when an admin updates a Syncro integration.
syncro_integration_delete Created when an admin deletes a Syncro integration.
syncro_billing_mapping_create Created when an admin creates a Syncro billing mapping.
syncro_billing_mapping_update Created when an admin updates a Syncro billing mapping.
syncro_billing_mapping_delete Created when an admin deletes a Syncro billing mapping.
syncro_company_mapping_create Created when an admin creates a Syncro company mapping.
syncro_company_mapping_update Created when an admin updates a Syncro company mapping.
syncro_company_mapping_delete Created when an admin deletes a Syncro company mapping.
syncro_settings_update Created when an admin updates Syncro settings.

RADIUS Events

Event Description
radius_auth User authenticates to RADIUS.

SSO Events

Event Description
sso_auth User authenticates to an SSO application.

Systems Events

Event Description
login_attempt User authenticates to a system.
system_fde_key_update A system's full disk encryption key updates.
user_password_change User password changes on a system.
user_lockout User is locked out of a system.
system_fde_key_decrypt A device's full disk encryption key was decrypted.
os_minor_upgrade An upgrade event with an increase in the minor patch, or revision attributes and no change to the major and release name attributes.
os_major_upgrade An upgrade event where the major attribute increases and the release name changes.
os_minor_rollback A rollback event with a decrease in the minor, patch, or revision attributes and no change to the major and release name attributes.
os_major_rollback A rollback event where the major attribute decreases and the release name changes.
remote_session_start Admin starts a remote-assist session.
remote_session_join End user joins a remote assist session, or the admin or end user rejoins an ongoing session when they get disconnected due to network failure or page refresh.
remote_session_end The remote-assist session is terminated by the administrator or the end user.
remote_session_feedback An administrator or end user provides feedback on a remote-assist session.
google_emm_create An administrator has registered for Android EMM.
google_emm_delete An administrator has deleted Android EMM registration.
google_emm_patch An administrator has modified Android EMM registration.
device_command An administrator has issued a command to an Android device.

Password Manager Events

Event Description
passwordmanager_enable Enable password manager for organization.
passwordmanager_disable Disable password manager for organization.
passwordmanager_user_enable Enable password manager for user.
passwordmanager_user_disable Disable password manager for user.
passwordmanager_user_activate User activates password manager.
passwordmanager_user_deactivate User deactivates password manager.
passwordmanager_user_reactivate User reactivates password manager.
passwordmanager_folder_create Folder created.
passwordmanager_folder_delete Folder deleted.
passwordmanager_folder_member_add Member added to folder.
passwordmanager_folder_member_update Member updated in folder.
passwordmanager_folder_member_remove Member removed from folder.
passwordmanager_item_add Item added to a folder.
passwordmanager_item_update Item updated in folder.
passwordmanager_item_remove Item removed from folder.
passwordmanager_item_move Item moved from a folder to another.
passwordmanager_user_device_pair User paired a new device.
passwordmanager_user_device_unpair User unpaired an existing device.
passwordmanager_user_signup User signup to PWM using an enrolled email.
passwordmanager_user_re-enable User re-enabled for activation.
passwordmanager_user_update User details updated from the Admin Portal.
passwordmanager_backup_create Create a cloud backup.
passwordmanager_backup_request Create a request to restore a cloud backup.
passwordmanager_backup_key_create Create a backup key.
passwordmanager_backup_key_delete Delete a backup key.
passwordmanager_backup_request_restore Restore an approved backup request.
passwordmanager_backup_enable Enable cloud backup feature.
passwordmanager_backup_disable Disable cloud backup feature.
passwordmanager_backup_key_regenerate Regenerate a new backup key.
passwordmanager_backup_request_cancel Cancel a request to restore a cloud backup.
passwordmanager_backup_request_reject Reject a request to restore a cloud backup.
passwordmanager_backup_request_approve Approve a request to restore a cloud backup.
passwordmanager_backup_request_restore Restore a backup of an approved request.
passwordmanager_sharedfolders_policy_group_add Add permission for a specific group to share folders.
passwordmanager_sharedfolders_policy_user_add Add permission for a specific group to share folders.
passwordmanager_sharedfolders_policy_group_remove Delete group permission to share folders.
passwordmanager_sharedfolders_policy_user_remove Delete user permission to share folders.
passwordmanager_sharedfolders_policy_update Update shared folders policy.
passwordmanager_user_remove Delete user from JC.
passwordmanager_folder_group_add Add group to a shared folder.
passwordmanager_folder_group_update Update the group role inside a shared folder.
passwordmanager_folder_group_remove Remove group access to a shared folder.
passwordmanager_folder_update Update folder details.
passwordmanager_item_reveal Reveal item in the desktop app/browser extension.
passwordmanager_item_copy Copy item from the desktop app/browser extension.
passwordmanager_item_autofill Autofill item in the browser extension.
passwordmanager_force_sync Force sync the desktop app.
passwordmanager_app_update Update the desktop app.
passwordmanager_local_backup_create Create a local backup.
passwordmanager_items_export Export items locally.
passwordmanager_pincode_update Update the desktop app pincode.
passwordmanager_local_backup_path_update Update local backup path.
passwordmanager_paranoid_mode_enable Enable paranoid mode in the desktop app/browser extension.
passwordmanager_paranoid_mode_disable Disable paranoid mode in the desktop app/browser extension.
passwordmanager_extension_settings_update Update the browser extension settings.
passwordmanager_item_settings_update Update item settings in the browser extension.
passwordmanager_folder_force_sync Force sync of a folder.
passwordmanager_items_import Import items.
passwordmanager_local_backup_restore Restore a local backup.
passwordmanager_mini_launch Launch password manager mini.
passwordmanager_app_unlock Unlock the desktop app.
passwordmanager_item_history_reveal Reveal item history.
passwordmanager_item_history_restore Restore item from history.
passwordmanager_extension_unlock Unlock the browser extension.
passwordmanager_extension_pair Pair a browser extension.
passwordmanager_extension_site_exclusion Exclude site from the browser extension.

Software Events

Event Description
software_add Event when a software is added.
software_change Event when a software is changed.
software_remove Event when a software is removed.
software_add_request Event when a software is added from Admin Portal.
software_change_request Event when a software is changed from Admin Portal.
software_remove_request Event when a software is removed from Admin Portal.

LDAP Events

Event Description
ldap_bind User authenticates to an LDAP directory server.
ldap_search LDAP search operation performed.

MDM Events

Event Description
mdm_command_result MDM command result.
device_enrollment Microsoft MDM successful enrollment.
configuration_file_download Microsoft MDM configuration file download.

Object Storage Events

Event Description
object_storage_create Object storage item is created.
object_storage_upload_validation_result The result of an object storage version's validation.
object_storage_get_download_url_request A request for a object storage item's download URL.
object_storage_delete Object storage item is deleted.

Alert Events

Event Description
alert_created Alert item is created.
alert_updated Alert item is updated.
alert_status_updated Alert status is updated.
rule_created Rule item is created.
rule_modified Rule item is updated.
rule_deleted Rule status is updated.

SaaS Management Events

Event Description
saas_management_enable SaaS Management enabled for the organization.
saas_management_disable SaaS Management disabled for the organization.
saas_management_settings_update SaaS Management settings updated.
saas_management_application_discover SaaS Management application discovered.
saas_management_event_application_review SaaS Management application reviewed.
saas_management_application_update SaaS Management application updated.
saas_management_application_access_restriction_update SaaS Management application access restriction configuration is updated.
saas_management_application_license_update SaaS Management application license updated.

Access Management Events

Event Description
access_management_access_request Access Management request is created.
access_management_access_request_approval Access Management request is approved or denied
access_management_association_change Access Workflow request is executed
access_management_workflow_create Access Workflow is created.
access_management_workflow_update Access Workflow is updated.
access_management_workflow_delete Access Workflow is deleted.
access_management_workflow_settings_update Access Workflow settings is updated.

EventDistinctQuery

Query event distinct field values

Query the API for a list of distinct values for a field

Sample Request

curl -X POST 'https://api.jumpcloud.com/insights/directory/v1/events/distinct' -H 'Content-Type: application/json' -H 'x-api-key: REPLACE_KEY_VALUE' --data '{"service": ["all"], "start_time": "2021-07-14T23:00:00Z", "end_time": "2021-07-28T14:00:00Z", "sort": "DESC", "field": "event_type"}'
scopes: ["directoryinsights.readonly"]
Authorizations:
(x-api-keyx-org-id)
Request Body schema: application/json

JSON event distinct query body

end_time
string <date-time>

optional query end time, UTC in RFC3339 format

service
required
Array of strings
Items Enum: "alerts" "all" "directory" "ldap" "mdm" "object_storage" "password_manager" "radius" "reports" "saas_app_management" "software" "sso" "systems" "access_management"

service name to query.

start_time
required
string <date-time>

query start time, UTC in RFC3339 format

field
required
string

field is what they wish to query on

object (SearchTerm)

SearchTerm is the filter portion of the query it contains only one of 'and', 'or', or 'not' conjunction maps

Responses

Request samples

Content type
application/json
{
  • "end_time": "2019-08-24T14:15:22Z",
  • "service": [
    ],
  • "start_time": "2019-08-24T14:15:22Z",
  • "field": "string",
  • "search_term": {
    }
}

Response samples

Content type
application/json
{
  • "buckets": [
    ],
  • "doc_count_error_upper_bound": 0,
  • "sum_other_doc_count": 0
}

EventIntervalQuery

Query event counts by bucketed by a time interval

Query the API for a list of counts by time interval

Sample Request

curl -X POST 'https://api.jumpcloud.com/insights/directory/v1/events/interval' -H 'Content-Type: application/json' -H 'x-api-key: REPLACE_KEY_VALUE' --data '{"service": ["all"], "start_time": "2021-07-14T23:00:00Z", "end_time": "2021-07-28T14:00:00Z", "timezone": "-0500", "interval_unit": "h", "interval_value": "2"}'
scopes: ["directoryinsights.readonly"]
Authorizations:
(x-api-keyx-org-id)
Request Body schema: application/json

JSON event interval query body

end_time
string <date-time>

optional query end time, UTC in RFC3339 format

service
required
Array of strings
Items Enum: "alerts" "all" "directory" "ldap" "mdm" "object_storage" "password_manager" "radius" "reports" "saas_app_management" "software" "sso" "systems" "access_management"

service name to query.

start_time
required
string <date-time>

query start time, UTC in RFC3339 format

interval_unit
required
string
Enum: "s" "m" "h" "d" "w"
interval_value
string

Interval Value. This specifies how many units you want to bucket the event counts by

q
string

optional string for specifying a full text query

object (SearchTerm)

SearchTerm is the filter portion of the query it contains only one of 'and', 'or', or 'not' conjunction maps

timezone
string

TimeZone. Specify the timezone in which the user is in optional

Responses

Request samples

Content type
application/json
{
  • "end_time": "2019-08-24T14:15:22Z",
  • "service": [
    ],
  • "start_time": "2019-08-24T14:15:22Z",
  • "interval_unit": "s",
  • "interval_value": "string",
  • "q": "string",
  • "search_term": {
    },
  • "timezone": "string"
}

Response samples

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

EventQuery

Query Events

Query the API for Directory Insights events

Sample Request

curl -X POST 'https://api.jumpcloud.com/insights/directory/v1/events' -H 'Content-Type: application/json' -H 'x-api-key: REPLACE_KEY_VALUE' --data '{"service": ["all"], "start_time": "2021-07-14T23:00:00Z", "end_time": "2021-07-28T14:00:00Z", "sort": "DESC", "fields": ["timestamp", "event_type", "initiated_by", "success", "client_ip", "provider", "organization"]}'
scopes: ["directoryinsights.readonly"]
Authorizations:
(x-api-keyx-org-id)
Request Body schema: application/json

JSON event query body

end_time
string <date-time>

optional query end time, UTC in RFC3339 format

service
required
Array of strings
Items Enum: "alerts" "all" "directory" "ldap" "mdm" "object_storage" "password_manager" "radius" "reports" "saas_app_management" "software" "sso" "systems" "access_management"

service name to query.

start_time
required
string <date-time>

query start time, UTC in RFC3339 format

fields
Array of strings

optional list of fields to return from query

limit
integer <int64>

Max number of rows to return

q
string

optional string for specifying a full text query

search_after
Array of objects

Specific query to search after, see x-* response headers for next values

object (SearchTerm)

SearchTerm is the filter portion of the query it contains only one of 'and', 'or', or 'not' conjunction maps

sort
string

ASC or DESC order for timestamp

Responses

Request samples

Content type
application/json
{
  • "end_time": "2019-08-24T14:15:22Z",
  • "service": [
    ],
  • "start_time": "2019-08-24T14:15:22Z",
  • "fields": [
    ],
  • "limit": 0,
  • "q": "string",
  • "search_after": [
    ],
  • "search_term": {
    },
  • "sort": "string"
}

Response samples

Content type
application/json
[
  • { }
]

Count Events

Query the API for a count of matching events

Sample Request

curl -X POST 'https://api.jumpcloud.com/insights/directory/v1/events/count' -H 'Content-Type: application/json' -H 'x-api-key: REPLACE_KEY_VALUE' --data '{"service": ["all"], "start_time": "2021-07-14T23:00:00Z", "end_time": "2021-07-28T14:00:00Z", "sort": "DESC", "fields": ["timestamp", "event_type", "initiated_by", "success", "client_ip", "provider", "organization"]}'
scopes: ["directoryinsights.readonly"]
Authorizations:
(x-api-keyx-org-id)
Request Body schema: application/json

JSON event query body

end_time
string <date-time>

optional query end time, UTC in RFC3339 format

service
required
Array of strings
Items Enum: "alerts" "all" "directory" "ldap" "mdm" "object_storage" "password_manager" "radius" "reports" "saas_app_management" "software" "sso" "systems" "access_management"

service name to query.

start_time
required
string <date-time>

query start time, UTC in RFC3339 format

fields
Array of strings

optional list of fields to return from query

limit
integer <int64>

Max number of rows to return

q
string

optional string for specifying a full text query

search_after
Array of objects

Specific query to search after, see x-* response headers for next values

object (SearchTerm)

SearchTerm is the filter portion of the query it contains only one of 'and', 'or', or 'not' conjunction maps

sort
string

ASC or DESC order for timestamp

Responses

Request samples

Content type
application/json
{
  • "end_time": "2019-08-24T14:15:22Z",
  • "service": [
    ],
  • "start_time": "2019-08-24T14:15:22Z",
  • "fields": [
    ],
  • "limit": 0,
  • "q": "string",
  • "search_after": [
    ],
  • "search_term": {
    },
  • "sort": "string"
}

Response samples

Content type
application/json
{
  • "count": 0
}

Reports

Get a list of report metadata

Ordered list of report metadata

scopes: ["directoryinsights.readonly"]
Authorizations:
(x-api-keyx-org-id)
query Parameters
sort
string
Enum: "CREATED_AT" "EXPIRATION" "REQUESTER_EMAIL" "STATUS" "TYPE" "UPDATED_AT" "-CREATED_AT" "-EXPIRATION" "-REQUESTER_EMAIL" "-STATUS" "-TYPE" "-UPDATED_AT"

Sort type and direction. Default sort is descending, prefix with - to sort ascending.

Responses

Request samples

curl --request GET \
  --url 'https://api.jumpcloud.com/insights/directory/v1/reports?sort=SOME_STRING_VALUE' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
[
  • {
    }
]

Download a report

Download a report by report ID and artifact ID

scopes: ["directoryinsights.readonly"]
Authorizations:
(x-api-keyx-org-id)
path Parameters
report_id
required
string

Report ID

artifact_id
required
string

Artifact ID

Responses

Request samples

curl --request GET \
  --url https://api.jumpcloud.com/insights/directory/v1/reports/{report_id}/artifacts/{artifact_id}/content \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
"string"

Request a report

Request a JumpCloud report to be generated asynchronously

scopes: ["directoryinsights.readonly"]
Authorizations:
(x-api-keyx-org-id)
path Parameters
report_type
required
string
Enum: "browser-patch-policy" "os-patch-policy" "os-version" "software-inventory" "user-account-health" "users-to-devices" "users-to-directories" "users-to-ldap-servers" "users-to-radius-servers" "users-to-sso-applications" "users-to-user-groups"

Report Type

Responses

Request samples

curl --request POST \
  --url https://api.jumpcloud.com/insights/directory/v1/reports/{report_type} \
  --header 'accept: application/json' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "artifacts": [
    ],
  • "created_at": "string",
  • "expiration": "string",
  • "id": "string",
  • "parameters": [
    ],
  • "requester_email": "string",
  • "requester_id": "string",
  • "status": "PENDING",
  • "type": "browser-patch-policy",
  • "updated_at": "string"
}