Skip to main content

​
About JumpCloud

JumpCloud is a cloud directory platform for identity, access, and device management. Serval connects to your JumpCloud organization with an administrator API key and works against both of JumpCloud’s API versions (v1 and v2) behind the scenes. A single connection covers syncing users and user groups into Serval, granting and revoking group membership for access management, and calling any JumpCloud API endpoint from your workflows. Authentication: API key (a JumpCloud administrator API key, plus an optional Organization ID for multi-tenant admins) Data sync: Users, user groups, and group memberships are fully refreshed every 4 hours. Access changes (granting or revoking group membership) and all other API calls run on demand when a workflow executes, not on the sync schedule.

​
What the JumpCloud integration enables

Anything defined in the JumpCloud API can be accessed through Serval.

​
Get your credentials

Serval connects with a JumpCloud administrator API key, generated from the admin’s own profile in the JumpCloud Admin Portal. The key is tied to that individual administrator and inherits their permissions - for full functionality, the admin must be able to read users and groups and modify user group membership. See the JumpCloud API documentation for background.
1

Sign in to the JumpCloud Admin Portal

Go to the JumpCloud Admin Portal and sign in as the administrator whose key Serval will use.
2

Open your API key settings

Click your avatar (initials) in the top-right corner and choose “My API Key”.
3

Generate and copy the key

Click “Generate New API Key” and copy the key immediately.
4

Multi-tenant admins: copy your Organization ID

If you are a multi-tenant (MTP/MSP) admin, also copy your Organization ID from Settings > Organization ID in the JumpCloud admin console. Single-organization admins can skip this.
The API key is not shown again after you close the dialog. Copy it before closing, or you will need to generate a new one.
Because the key inherits the individual administrator’s permissions, pick an admin who can read users and groups and modify group membership. A key from a more limited admin will connect but fail later (see Gotchas).

​
Connect in Serval

1

Open the JumpCloud connect form

In Serval, open the JumpCloud integration and start a new connection.
2

Instance Name (optional)

A free-text display name for this connection inside Serval. Any value is accepted, including blank.
3

API Key (required)

Paste your JumpCloud administrator API key. This is a password-type field labeled “API Key *”. Submitting it blank shows the inline error “This field is required”. There is no format validation - whatever you paste is saved as entered.
4

Organization ID (optional)

Multi-tenant (MTP/MSP) admins only. The form describes it as: “Optional: For multi-tenant JumpCloud admins. Find this in Settings > Organization ID in the JumpCloud admin console.” Single-organization admins should leave it blank.
5

Connect

Submit the form. On success you will see the toast “JumpCloud connected successfully” and Serval automatically runs the connection health checks. If the connection fails, you will see the toast “Failed to connect service”.
Serval stores your API key as a secret. After saving, it is shown obfuscated (bullet characters plus the last 4 characters), and it is only ever sent to console.jumpcloud.com.
When editing the connection later, re-enter the API Key in full every time you save - paste the complete key, not the obfuscated placeholder - and re-enter the Organization ID in full as well if you use one. Do not clear pre-filled fields you are not changing. A successful update shows the toast “JumpCloud updated”.

​
Verifying the connection

After you connect, Serval runs three health checks against your JumpCloud organization and reports the result of each one. Test JumpCloud Connection - makes a minimal call to list groups, confirming your stored API key authenticates with JumpCloud.
  • Success: “Successfully authenticated with JumpCloud”
  • Failure: “Unable to connect to JumpCloud.” followed by a status-specific message:
    • Invalid or expired key (401): “The API key is invalid or expired. Please verify your API key in the JumpCloud integration settings.”
    • Insufficient permissions (403): “The API key is not authorized to access JumpCloud. Please ensure the key has been granted the necessary permissions.”
    • JumpCloud server error (500/502/503): “JumpCloud returned a server error during authentication. This is likely a temporary issue - please try again later.”
List JumpCloud Users - lists up to 100 users (the reported count caps at 100).
  • Success: “Successfully listed [number] users from JumpCloud”
  • Failure: “Unable to list users from JumpCloud.” followed by a status-specific message:
    • 401: “The JumpCloud API key may be invalid or expired. Please verify your API key is correct.”
    • 403: “The JumpCloud API key may not have the required permissions. Please check that the necessary privileges are granted.”
    • 404: “The requested JumpCloud resource was not found. This may indicate missing permissions or an incorrect configuration.”
    • 500/502/503: “JumpCloud returned a server error. This is likely a temporary issue with JumpCloud’s API - please try again later.”
List JumpCloud Groups - lists up to 100 groups (the reported count caps at 100), with the same status-specific failure messages as List JumpCloud Users.
  • Success: “Successfully listed [number] groups from JumpCloud”
  • Failure: “Unable to list groups from JumpCloud.”
All three checks can pass while access workflows still fail: the checks only read users and groups, but provisioning also requires the right to modify group membership. If add-to-group or remove-from-group workflows fail, confirm the administrator who owns the key can modify user group membership - and if you are a multi-tenant admin, that the Organization ID is set on the connection.

​
Gotchas and troubleshooting

Whenever you save changes to the connection settings - even if you are only changing something else - paste the complete API Key value rather than leaving the obfuscated placeholder, and for multi-tenant orgs re-enter the Organization ID as well. Do not clear pre-filled fields you are not changing. If the connection stops working after an edit, re-enter the API Key (and Organization ID, if you use one) in full and save again.
Serval only scopes calls to a specific organization when an Organization ID is configured on the connection. A multi-tenant admin API key used without it can return missing data, not-found errors, or data from the wrong organization. Single-organization admins should leave the field blank. The ID is in Settings > Organization ID in the JumpCloud admin console.
The key inherits that admin’s permissions. For full functionality (user sync, group sync, and access provisioning), the administrator must be able to read users and groups and modify user group membership. A 403 from a health check means the key authenticates but lacks one of these rights.
Add-to-group and remove-from-group workflows look up the target user in JumpCloud by their email address. The workflow fails with “No user found with email: [email]” if there is no match, or “Multiple users found with email: [email]” if there is more than one - the email must match exactly one JumpCloud user.
For workflow authors using the generic API request actions: JumpCloud’s v1 API wraps list results in an object containing a results list and a total count, while the v2 API returns lists directly. Both paginate with skip and limit parameters; 100 per page is the recommended size. Prefer v2 where an endpoint exists in both versions.
Connecting: success shows “JumpCloud connected successfully”; failure shows “Failed to connect service”. Saving changes to an existing connection: success shows “JumpCloud updated”; failures begin “Failed to install integration” or “Failed to update integration” (with detail appended when available), or fall back to “Failed to save configuration. Please try again.”.
Need help? Contact support@serval.com for assistance with your JumpCloud integration.