A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The JumpCloud API is how an app or AI agent works with a company's directory: listing and updating enrolled devices, creating and deleting users, adding people to groups, and reading a record of who signed in to what. Access is granted through an API key tied to one admin, and the key inherits that admin's full role, so it reaches everything that admin can, with no narrower per-endpoint permission. There is no general webhook push; Directory Insights is the event source an integration queries for directory activity.
How an app or AI agent connects to JumpCloud determines what it can reach. The directory exposes two API generations and a hosted MCP server, and each call is governed by the API key behind it and the admin role that key inherits.
Version 1 answers at https://console.jumpcloud.com/api and covers the core objects: devices, users, commands, and organization details. Each request carries the API key in the x-api-key header.
Version 2 answers at https://console.jumpcloud.com/api/v2 and covers group membership and the associations between objects, like which users belong to a group or which devices a policy applies to.
JumpCloud's hosted MCP server lets an agent manage the directory in natural language. The remote endpoint at https://mcp.jumpcloud.com/v1 supports API key and OAuth authentication and currently exposes tools only, not resources or prompts. It is available to all customers.
Directory Insights answers at https://api.jumpcloud.com through a single events endpoint. An app or AI agent queries it for a record of directory activity, since JumpCloud has no general webhook push system.
A JumpCloud API key is sent in the x-api-key header and is tied to one admin. It carries that admin's full role, so it can reach everything the admin can, with no per-endpoint scope. Keys are prefixed with jca_ and default to a 90-day expiry for admins created after 15 July 2024.
A service account is an API-only identity, separate from a person's admin login, used so an integration's key is not tied to an individual. It still inherits an admin role rather than a narrower set of permissions.
The hosted MCP server also accepts browser-based OAuth, which generates a token and enables MCP with the client. Some clients, like Claude, use OAuth only.
The JumpCloud API is split into areas an agent can act on, such as devices, users, groups, commands, and applications. Each area has its own methods, and some change real directory and device state.
List the devices enrolled in the directory, read a single device, update a device, and remove a device.
List the people in the directory, read a single user, create a user, update a user, and delete a user.
List user groups, read and create a group, and add or remove people from a group's membership.
List device groups, read and create a group, and add or remove devices from a group's membership.
List the commands defined in the directory, read a single command, create a command, update a command, and delete a command.
Read which users and user groups are bound to a single sign-on application, and change those bindings.
List the configuration policies in the directory, read a single policy, and create a policy.
Read which users and user groups are bound to a RADIUS server, and change those bindings.
Query a record of directory activity, like admin changes, user logins, and device events.
Read the details and settings of the JumpCloud organization the key belongs to.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
DevicesList the devices enrolled in the directory, read a single device, update a device, and remove a device.4 | ||||||
| GET | /systems | List the devices enrolled in the directory. | read | — | Current | |
A v1 endpoint. The API key has no per-endpoint scope; it inherits the role of the admin it belongs to. Acts ondevice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /systems/{id} | Get a single enrolled device by its id. | read | — | Current | |
A v1 endpoint. The API key inherits the admin's role, so what it can read follows that admin's permissions. Acts ondevice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /systems/{id} | Update an enrolled device's settings. | write | — | Current | |
A v1 endpoint. JumpCloud has no granular per-endpoint scopes; the key carries the admin's full role. Acts ondevice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /systems/{id} | Delete an enrolled device from the directory. | write | — | Current | |
A v1 endpoint. Deleting a device unenrolls it. The key inherits the admin's role. Acts ondevice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersList the people in the directory, read a single user, create a user, update a user, and delete a user.5 | ||||||
| GET | /systemusers | List the people in the directory. | read | — | Current | |
A v1 endpoint. JumpCloud calls a directory person a system user. The key inherits the admin's role. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /systemusers/{id} | Get a single user by id. | read | — | Current | |
A v1 endpoint. Returns the person's profile and attributes. The key inherits the admin's role. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /systemusers | Create a user in the directory. | write | — | Current | |
A v1 endpoint. JumpCloud has no granular per-endpoint scopes; the key carries the admin's full role. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /systemusers/{id} | Update a user's profile or attributes. | write | — | Current | |
A v1 endpoint. The key inherits the admin's role. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /systemusers/{id} | Delete a user from the directory. | write | — | Current | |
A v1 endpoint. Deleting a user removes their access across everything bound to them. The key inherits the admin's role. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
User groupsList user groups, read and create a group, and add or remove people from a group's membership.5 | ||||||
| GET | /usergroups | List all user groups. | read | — | Current | |
A v2 endpoint. Group membership and object relationships live in v2. The key inherits the admin's role. Acts onuser group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /usergroups/{id} | Get a single user group by id. | read | — | Current | |
A v2 endpoint. The key inherits the admin's role. Acts onuser group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /usergroups | Create a user group. | write | — | Current | |
A v2 endpoint. The key inherits the admin's role. Acts onuser group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /usergroups/{group_id}/members | List the members of a user group. | read | — | Current | |
A v2 endpoint. The key inherits the admin's role. Acts onuser group membership Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /usergroups/{group_id}/members | Add or remove a person from a user group, sent as an add or remove operation. | write | — | Current | |
A v2 endpoint. One endpoint handles both adding and removing through an op field in the body. The key inherits the admin's role. Acts onuser group membership Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Device groupsList device groups, read and create a group, and add or remove devices from a group's membership.4 | ||||||
| GET | /systemgroups | List all device groups. | read | — | Current | |
A v2 endpoint. JumpCloud calls a device group a system group. The key inherits the admin's role. Acts ondevice group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /systemgroups | Create a device group. | write | — | Current | |
A v2 endpoint. The key inherits the admin's role. Acts ondevice group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /systemgroups/{group_id}/members | List the members of a device group. | read | — | Current | |
A v2 endpoint. The key inherits the admin's role. Acts ondevice group membership Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /systemgroups/{group_id}/members | Add or remove a device from a device group, sent as an add or remove operation. | write | — | Current | |
A v2 endpoint. One endpoint handles both adding and removing through an op field in the body. The key inherits the admin's role. Acts ondevice group membership Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CommandsList the commands defined in the directory, read a single command, create a command, update a command, and delete a command.5 | ||||||
| GET | /commands | List the commands defined in the directory. | read | — | Current | |
A v1 endpoint. A command holds code that can run on enrolled devices. The key inherits the admin's role. Acts oncommand Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /commands/{id} | Get a single command by id. | read | — | Current | |
A v1 endpoint. The key inherits the admin's role. Acts oncommand Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /commands | Create a command. | write | — | Current | |
A v1 endpoint. Defines code that can later run on devices. The key inherits the admin's role. Acts oncommand Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /commands/{id} | Update a command's definition. | write | — | Current | |
A v1 endpoint. Changing a command changes the code that runs on devices. The key inherits the admin's role. Acts oncommand Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /commands/{id} | Delete a command. | write | — | Current | |
A v1 endpoint. The key inherits the admin's role. Acts oncommand Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Applications (SSO)Read which users and user groups are bound to a single sign-on application, and change those bindings.3 | ||||||
| GET | /applications/{application_id}/users | List the users bound to a single sign-on application. | read | — | Current | |
A v2 endpoint. Shows who can sign in to the application. The key inherits the admin's role. Acts onapplication binding Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /applications/{application_id}/associations | List the associations of a single sign-on application. | read | — | Current | |
A v2 endpoint. The key inherits the admin's role. Acts onapplication binding Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /applications/{application_id}/associations | Add or remove an association on a single sign-on application, sent as an add or remove operation. | write | — | Current | |
A v2 endpoint. Changes who can sign in to the application. The key inherits the admin's role. Acts onapplication binding Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PoliciesList the configuration policies in the directory, read a single policy, and create a policy.3 | ||||||
| GET | /policies | List the configuration policies in the directory. | read | — | Current | |
A v2 endpoint. A policy is configuration enforced on enrolled devices. The key inherits the admin's role. Acts onpolicy Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /policies/{id} | Get a single policy by id. | read | — | Current | |
A v2 endpoint. The key inherits the admin's role. Acts onpolicy Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /policies | Create a configuration policy. | write | — | Current | |
A v2 endpoint. Defines configuration that gets enforced on enrolled devices. The key inherits the admin's role. Acts onpolicy Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RADIUSRead which users and user groups are bound to a RADIUS server, and change those bindings.2 | ||||||
| GET | /radiusservers/{radiusserver_id}/users | List the users bound to a RADIUS server. | read | — | Current | |
A v2 endpoint. Shows who can authenticate through the network RADIUS server. The key inherits the admin's role. Acts onradius binding Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /radiusservers/{radiusserver_id}/associations | Add or remove an association on a RADIUS server, sent as an add or remove operation. | write | — | Current | |
A v2 endpoint. Changes who can authenticate through the RADIUS server. The key inherits the admin's role. Acts onradius binding Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Directory InsightsQuery a record of directory activity, like admin changes, user logins, and device events.1 | ||||||
| POST | /insights/directory/v1/events | Query a record of directory activity, like admin changes, user logins to the portal, RADIUS, LDAP and SSO apps, and device events. | read | — | Current | |
Served from api.jumpcloud.com, separate from the console host. The request is a POST that carries the query in its body, and it reads the activity record. The key inherits the admin's role. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrganizationRead the details and settings of the JumpCloud organization the key belongs to.1 | ||||||
| GET | /organizations | Get the details of the JumpCloud organization the key belongs to. | read | — | Current | |
A v1 endpoint. Returns organization-wide settings. The key inherits the admin's role. Acts onorganization Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
JumpCloud has no general webhook system. Instead, Directory Insights is the event source: an app or AI agent queries it for a record of directory activity, like admin changes, user logins, and device events, rather than receiving pushed notifications.
| Event | What it signals | Triggered by |
|---|
JumpCloud limits how fast an app or AI agent can call, and a request over the limit returns a 429 response. Lists are paged with skip and limit parameters, and going over a limit calls for an exponential backoff before retrying.
JumpCloud limits how fast an app or AI agent can call, and a request that goes over returns a 429 response, which the documentation classes as a temporary error. The best-practice guidance is to retry with an exponential backoff, doubling the wait each time, for example 30 seconds, then 60, then 120, then 240. The exact ceiling in requests per second is not published on the best-practices page, so an integration should treat 429 as the signal to slow down rather than assume a fixed number.
List endpoints page with the skip and limit query parameters, where skip is how many records to step past and limit is how many to return. When stepping through a large list with skip, the guidance is to add sort set to _id so the order stays stable across pages. Directory Insights returns its own pagination token in a response header for fetching the next page of events.
Requests and responses are JSON. The best-practices page does not state a fixed payload or response size limit; large reads are handled through pagination rather than a single large response.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | The API key is missing, invalid, or expired. JumpCloud treats this as a permanent error that retrying will not fix. | Send a valid, unexpired key in the x-api-key header, or regenerate the key if it has expired. |
| 403 | Forbidden | The key is valid but the admin it belongs to lacks the role needed for this action. | Use a key whose admin has the required role, since JumpCloud has no per-endpoint scopes to grant. |
| 404 | Not Found | The object does not exist, or the path is wrong. | Confirm the object id and the endpoint path before retrying. |
| 409 | Conflict | The request conflicts with the current state, such as creating an object that already exists. | Refetch the current state and resolve the conflict before retrying. |
| 429 | Rate limit exceeded | Too many requests were sent in a short window. JumpCloud treats this as a temporary error. | Back off and retry with an exponential delay, doubling the wait on each attempt. |
| 500 | Internal Server Error | A server-side fault. JumpCloud groups 5xx responses as temporary errors that may clear on their own. | Retry with an exponential backoff, and stop after a sensible number of attempts. |
JumpCloud runs two API generations side by side. Version 1 covers devices, users, and commands, while version 2 covers group membership and the relationships between objects. Many integrations call both.
Version 1 is the original JumpCloud API, answering at the console host. It covers the core objects, like devices, users, commands, and organization details, with create, read, update, and delete operations. It is authenticated with the x-api-key header and remains in active use alongside version 2.
Version 2 answers under a /v2 path and was added to handle group membership and the associations between directory objects, the relationships version 1 did not model cleanly. It covers user groups, device groups, policies, and the bindings on applications and RADIUS servers. It uses the same x-api-key authentication, and integrations commonly call both generations.
An agent reaches version 1 for core objects and version 2 for group membership and associations.
JumpCloud API release notes ↗Bollard AI sits between a team's AI agents and JumpCloud. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.