---
name: jumpcloud-audit-events
description: Query JumpCloud Directory Insights audit events to reconstruct what happened — logins and login failures, admin actions, directory and MDM changes, SSO activity, and RADIUS or LDAP authentication. Use when investigating an incident, a lockout, suspicious activity, or a change nobody claims to have made, or when the user asks who did something, when it happened, or for an audit trail or evidence.
license: MIT
compatibility: Requires the JumpCloud MCP server (https://mcp.jumpcloud.com/v1) connected with an admin account or API key.
metadata:
  author: jumpcloud
  version: "1.1.0"
---

# Directory Insights

`di_events_get` is the audit log: who did what, when, from where. It is the only tool that
shows history — every other tool shows current state. When a question is about what
*happened* rather than what *is*, this is the tool.

## Scoping a query

| Parameter | Notes |
|---|---|
| `service` | One of `all`, `directory`, `systems`, `sso`, `ldap`, `radius`, `mdm`, `software`, `alert`, `reports`, `notifications`, `access_management`, `asset_management`, `saas_app_management`, `password_manager`, `object_storage`. Defaults to `all`. |
| `startTime` | Duration in the past (`30m`, `7d`, `1w`) or ISO 8601 (`2026-01-01T00:00:00Z`). Defaults to `7d`. |
| `query` | Free-text filter across events. |
| `exactMatch` | Exact-value filter across all fields. **Mutually exclusive with `query`** — pass one or the other, never both. |
| `initiatorId` | Restrict to actions taken by one user or admin. |
| `eventType` | Restrict to one event type. |
| `limit` | 1–1000, default 50. |

Always widen `startTime` before concluding nothing happened. The 7-day default silently
excludes anything older, and an empty result from a default-window query is the most common
false negative in an investigation. If a search returns `[]`, retry at `30d` or `90d` and
say which window you used.

Pick the narrowest `service` that covers the question — `sso` for application logins,
`systems` for device activity, `directory` for user and group changes, `mdm` for device
management commands, `access_management` for permission changes. Use `all` only when you do
not yet know where to look.

## Investigating

Work from a subject and a window, not from a hunch.

1. **Anchor.** Establish who or what, and over what period. Resolve a name to an ID first
   (`users_list` with `searchTerm`) so you can use `initiatorId`.
2. **Sweep wide, then narrow.** Start with `service: "all"` and a generous window to see
   the shape of activity, then re-query the specific service with a tighter filter.
3. **Build the timeline.** Order events and state it plainly: what happened, in what order,
   initiated by whom.
4. **Separate observation from inference.** "Fourteen failed logins from one IP, then a
   success at 03:12" is what the log says. "The account was compromised" is a conclusion —
   label it as one, and say what would confirm it.
5. **Corroborate.** `alerts_list` and `alert_occurrences` show what the platform already
   flagged; `health_rules_list` shows what it was watching at all. A silent alert log may
   mean nothing happened, or that no rule covered it. Do not read absence as safety.

## Common investigations

**Repeated lockouts.** Before `user_unlock`, query `service: "directory"` filtered to the
user. A pattern of failures from an unfamiliar source is an attack; a burst from one device
right after a password change is usually a stale credential in a mail client or a saved
Wi-Fi profile. The remedy differs, so determine which.

**An unexplained change.** Filter by `service` for the resource type and search the affected
object's name or ID with `exactMatch`. The event carries the initiator, which answers "who
did this" directly — much faster than reasoning from current state.

**Departed-employee activity.** Query with `initiatorId` set to the departing user across a
window that spans their notice period. Do this **before** offboarding removes group
memberships, because the events remain but the context for interpreting them does not.

**SSO usage and dormancy.** `service: "sso"` shows login attempts. Pair it with
`saas_application_accounts_list` and its `loginMethods` array: an account with
`"APPLICATION"` but not `"SSO"` is logging in directly to the vendor and will never appear
in SSO events. Absence from DI is not absence of use.

## Reporting

Give the window, the filter, and the count before the narrative, so the reader can judge
the evidence:

> `service: sso`, last 30 days, 412 events. Three failed logins for alice@example.com from
> 198.51.100.4 on 3 March at 02:41–02:44, then a success from her usual address at 09:12.
> The failures came from a network the account has never used before. That is consistent
> with credential stuffing, though it is also consistent with a VPN — checking whether she
> was travelling would settle it.

State explicitly what you could not see. An org may not have the events retained, or the
query may have hit the `limit` — a truncated result reported as complete is worse than no
answer. If you hit the cap, say so and narrow the window rather than raising the limit and
hoping.