Directory Insights API

Directory Insights allows you to read event logs, view activity in your directory, and monitor user authentications to the User Portal, RADIUS, LDAP, and SSO apps. Directory Insights analyzes the audit trails that lead to critical events so you know all about your directory activities, including the what, where, when, how, and who. You can monitor:

• Alert Events: Creation and status updates of alerts in JumpCloud.
• Directory Events: Activity in JumpCloud Portals, including admin changes in the directory and admin / user authentications to the Admin and User Portals.
• Software Events: Application changes on a device.
• RADIUS Events: User authentications to RADIUS used for WiFi and VPNs.
• Systems Events (MacOS, Windows, and Linux): User authentications to devices, including agent-related events on lockout, OS upgrades and rollback events, password changes, and Full Disk Encryption. Only SSH login events are logged for Linux devices.
• LDAP Events: User authentications to LDAP, including LDAP bind and search event types.
• MDM Events: MDM command results.
• Managed Service Provider Events (MTP only): Activity in JumpCloud Multi-Tenant Portal (MTP) including admin changes, organization changes, and integration events.
• SSO: When an authorized SSO connector is created, updated, or deleted, as well as when a user authenticates to an SSO application.
• Password Manager: Invites, activations, and deactivation of users, as well as all events related to folders and their members, including their assigned permissions.
• Object Storage: Creation, uploads, URL generation, and deletion of custom software apps.

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.

For more information on the Directory Insights API, see the complete Directory Insights API documentation.

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.

Row Size Limit

By default, the system returns a maximum of 10,000 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.

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 search order used (based on the event timestamp), and other fields (limit).

Example Response Header:

Schemas

The schemas available in the Directory Insights API are:

• Directory Attributes
• MTP/MSP Events
• SSO Attributes
• RADIUS Attributes
• System Attributes
• Software Attributes
• LDAP Attributes
• MDM Attributes

The event types available in the Directory Insights API are:

• Directory - Object Events 
• Directory - User and Admin Events
• Directory - Command and Policy Events
• Directory - Integrations
• Directory - MTP/MSP Events
• RADIUS Events
• SSO Events
• System Events
• Software Events
• LDAP Events
• MDM Events
• Password Manager Events

The AWS Serverless App

The AWS Serverless Application automatically provisions all of the resources required to export JumpCloud Directory Insights Data into an AWS S3 bucket. For more information, see The JumpCloud Directory Insights AWS Serverless Application.

View Old API Keys Actively Being Used

The Directory Insights event ‘admin_old_api_key_attempt’ can be used to identify any old admin API key that’s still being used. When an admin API key is rotated, you’ll see these events until you replace all instances of your old admin API key with the newly rotated key value. Each attempted usage of an old admin API key will generate a new instance of this event detailing the extent of its usage.

To view old API Keys:

1. Log in to the JumpCloud Admin Portal.
2. In the left hand navigation, click INSIGHTS > Directory.
3. Select a Time Range.  Only events within that Time Range will be displayed.
4. In the Event Type dropdown menu, select admin_old_api_key_attempt to filter the events.
5. A list of results will populate if there are any old API keys being actively used for the selected Time Range.
   • You can also pinpoint usage by searching your code base for the specific JumpCloud API Path value ‘console.jumpcloud.com’ endpoint or for the following ‘api.jumpcloud.com’ path snippets:
     • ‘/insights/directory/v1’
     • ‘/reports’
     • ‘/import/users’
6. Click the dropdown arrow next to the timestamp of an event to see a Summary.
7. Click the JSON tab to see the event details to identify the source of where the old API key is being used. The following details are provided:
   • initiated_by: Identifies the admin who’s API key is being used.
   • client_ip: The IP Address from which the API call was sourced to JumpCloud.
   • geoip: Identifies the geography associated with the client IP address.
   • Resource:  Identifies the base URL for the JumpCloud API being called.
     • A URL of `console.jumpcloud.com` will also have a Path value, which specifies the API endpoint being called.
     • A URL of `api.jumpcloud.com` will be any endpoint in the Directory Insights API or SCIM Server API.
   • useragent: Standard information about the program making the api call.
8. Now, your old API key might be coming from various integrations with JumpCloud. You will have to generate a new API key and update any existing integrations that use an API key with the newly generated value. See which integrations use an API key below.

Accessing Your API Key and Generating a New One

See JumpCloud APIs to learn more.