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

# Service account setup

> Connect JumpCloud to Ravenna using OAuth 2.0 client credentials with a service account for token-based auth, automatic refresh, and granular roles.

OAuth 2.0 client credentials flow using a JumpCloud service account. Provides token-based authentication with automatic refresh.

## Prerequisites

Before you begin, ensure you have:

* JumpCloud Administrator access
* Permissions to create service accounts and custom admin roles in JumpCloud

## Setup guide

### Create service account in JumpCloud

<Steps>
  <Step title="Access JumpCloud Admin Console">
    Log in to your [JumpCloud Admin Console](https://console.jumpcloud.com)
  </Step>

  <Step title="Navigate to service accounts">
    Go to **Settings > Service Accounts** (or **User Authentication > Service Accounts** depending on your console version)
  </Step>

  <Step title="Create a new service account">
    1. Click **Create Service Account**
    2. Enter a name (e.g., "Ravenna")
    3. Create a [custom admin role](https://jumpcloud.com/support/custom-admin-roles) with the following permissions:
       * **Full User Management**
       * **Full Group Management**
       * **Device Management** (Devices & Mobile Device Management)
    4. Assign the custom role to the service account
    5. Save the service account
  </Step>

  <Step title="Generate client credentials">
    1. Select the service account you created
    2. Generate a **Client ID** and **Client Secret**
    3. Copy both values

    <Warning>
      Store the Client Secret securely. You will not be able to view it again.
    </Warning>
  </Step>
</Steps>

<Callout icon="link" color="#3B82F6">
  For more details, see [JumpCloud's service account documentation](https://jumpcloud.com/support/service-account-for-apis)
</Callout>

### Add integration in Ravenna

<Steps>
  <Step title="Navigate to integrations">
    Go to **Settings > Integrations**
  </Step>

  <Step title="Select JumpCloud">
    Find **JumpCloud** in the available integrations and click **Connect**
  </Step>

  <Step title="Select Service Account method">
    Select **Service Account** as your authentication method
  </Step>

  <Step title="Enter credentials">
    Provide the following information:

    <ParamField path="clientId" type="string" required>
      The Client ID from your JumpCloud service account
    </ParamField>

    <ParamField path="clientSecret" type="string" required>
      The Client Secret from your JumpCloud service account
    </ParamField>
  </Step>

  <Step title="Complete setup">
    Click **Add JumpCloud** to complete the integration. Ravenna will validate your credentials and begin syncing users and groups.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Invalid credentials error">
    **Cause**: Client ID or Client Secret is incorrect.

    **Solution**:

    * Verify the Client ID and Client Secret are copied correctly
    * Ensure there are no extra spaces or characters
    * Confirm the service account is still active in JumpCloud
  </Accordion>

  <Accordion title="Insufficient permissions error">
    **Cause**: The service account lacks the required permissions.

    **Solution**:

    * Verify the custom admin role includes Full User Management, Full Group Management, and Device Management
    * Check that the role is assigned to the service account
    * See [JumpCloud's custom admin roles documentation](https://jumpcloud.com/support/custom-admin-roles) for help configuring roles
  </Accordion>

  <Accordion title="Users or groups not syncing">
    **Cause**: Sync may still be in progress or the service account has limited scope. When the service account can't read a resource (users, groups, or applications), Ravenna keeps the integration connected and syncs that resource as empty rather than failing.

    **Solution**:

    * Allow a few minutes for the initial sync to complete
    * Verify the integration status shows as connected in **Settings > Integrations**
    * Check that users and groups exist in the JumpCloud organization linked to your credentials
    * Confirm the custom admin role grants read access to each resource type you expect to see, then trigger a resync from the integration page
  </Accordion>
</AccordionGroup>