> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JumpCloud

## After this article

You will be able to connect JumpCloud to Lumos to sync users, groups, and applications, manage group membership, and deprovision users, and optionally put Lumos itself behind JumpCloud SAML SSO.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Users | Account | Yes | Yes | User accounts, including custom attributes. Lumos can deprovision users |
| User Groups | Permission | Yes | Yes | Group membership. Lumos can add and remove users from groups |
| Applications | Permission | Yes | No | SSO applications and per-user app access (via group bindings) |

## Required plan and roles

* **JumpCloud plan:** no minimum JumpCloud plan is required.
* **JumpCloud role:** your JumpCloud user must be an **Administrator** or **Manager**.
* **Authentication:** an **Organization ID** plus an **API Key** (not OAuth). The API key is tied to the admin user who generates it.
* **Permission scoping:** this is a read/write integration. Lumos syncs users, groups, and applications, and also manages group membership and deprovisions users. Write access comes with the admin API key, and there is no separate scope selection.

## Read-only access vs provisioning

**Is read-only possible?** No. JumpCloud authenticates with a single admin API key that is tied to the connecting Administrator or Manager user, and there is no separate scope selection to narrow it to read-only.

**What full provisioning requires.** The same Organization ID and API Key described above, generated by a JumpCloud **Administrator** or **Manager**. Follow the steps below.

**Watch out for.** Because there's no scope selection, the API key that lets Lumos sync users and groups is the same key that manages group membership and deprovisions users. If the admin who generated the key is removed or the key is revoked, sync fails with "Unauthorized: api key user not found" and you have to regenerate the key with a qualifying user and reconnect.

## Instructions

**Phase 1: Get your Organization ID and API key in JumpCloud**

1. Log in at [console.jumpcloud.com/login](https://console.jumpcloud.com/login). If you land on the User Portal, select your initials in the top right and click **Launch Admin Portal**.
2. Click **Settings** at the bottom of the left-hand navigation panel.
3. Under **Organization Profile → General**, find and save your **Organization ID**.
4. Click your account initials in the top right and select **My API Key** to retrieve your API key.

**Phase 2: Connect in Lumos**

1. Find the JumpCloud card in your Lumos integrations (reconnect an existing card or add a new one).
2. Enter the **Organization ID** and **API Key** values from JumpCloud.
3. Click **Connect JumpCloud**.

**Optional: Put Lumos behind JumpCloud SAML SSO**

This restricts who can log in to Lumos via JumpCloud SAML. The ACS URL and SP Entity ID values are not self-service, so request them from Lumos support (Slack or [support@lumos.com](mailto:support@lumos.com)).

1. Log into the JumpCloud Admin console and create a custom SAML app (adding a Lumos logo is recommended).
2. Contact Lumos support to obtain the **Single sign on URL (ACS URL)** and **Audience URI (SP Entity ID)**.
3. In the app's **Single Sign-On Configuration**, set the ACS URL in the **ACS URL** field, and enter the SP Entity ID in **both** the **IdP Entity ID** and **SP Entity ID** fields. Save.
4. Configure attribute mappings (Name → Name Format): `id` → email, `email` → email, `firstName` → firstname, `lastName` → lastname.
5. Under the **SSO** tab, check **Sign Assertion** and save, then check **Declare Redirect endpoint**.
6. Under **JumpCloud Metadata** on the SSO tab, click **Export Metadata** and send the XML file to the Lumos team.
7. Assign users to the JumpCloud Lumos application.
8. After Lumos support confirms the configuration, verify login from the JumpCloud tile or the Lumos login page.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**Can't connect the integration.** Verify the Organization ID and API Key are correct, and that the user who generated the key is at least a **Manager** in JumpCloud.

**SSO setup stalls.** The ACS URL and SP Entity ID for the SAML app must come from Lumos support. They cannot be derived yourself. Also double-check that the SP Entity ID was entered in both the IdP Entity ID and SP Entity ID fields, a common misconfiguration.

**Sync fails with "Unauthorized: api key user not found".** The JumpCloud API key was revoked or expired, or the admin that owned it was removed. Regenerate the key with a connecting user that is at least a **Manager**, and reconnect.