> ## 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.

# Setup

> Connect HiBob to Ravenna using a HiBob service user with Basic Authentication to sync employees and groups, and enable time-off workflow actions.

Connect HiBob to Ravenna using a HiBob service user. Ravenna authenticates directly against the HiBob API with Basic Authentication (username and password).

## Prerequisites

Before you begin, ensure you have:

* HiBob admin access
* Permission to create service users and manage API integrations in HiBob

## Setup guide

### Create a HiBob service user

<Steps>
  <Step title="Open HiBob settings">
    Log in to HiBob and go to **Settings > Integrations > Service users**.
  </Step>

  <Step title="Create a new service user">
    1. Click **New service user**
    2. Enter a name (for example, `Ravenna`)
    3. Assign a permission group that grants read access to employees and groups, and write access to time-off (required for the **Create Time-off Request** workflow action)
    4. Save the service user
  </Step>

  <Step title="Generate the credentials">
    1. Open the new service user
    2. Generate the service user **ID** (used as the username) and **token** (used as the password)
    3. Copy both values

    <Warning>
      The token is shown only once. Store it in a secure location before leaving the page.
    </Warning>
  </Step>
</Steps>

### Add the integration in Ravenna

<Steps>
  <Step title="Navigate to integrations">
    Go to **Settings > Integrations** and find **HiBob** in the HRIS section.
  </Step>

  <Step title="Select Basic Authentication">
    Click **Connect**, then select **Basic Authentication** as your authentication method.
  </Step>

  <Step title="Enter credentials">
    Provide the values from your HiBob service user:

    <ParamField path="username" type="string" required>
      The HiBob service user ID.
    </ParamField>

    <ParamField path="password" type="string" required>
      The HiBob service user token.
    </ParamField>

    Ravenna combines these into a Base64-encoded `Authorization: Basic` header to call the HiBob API directly.
  </Step>

  <Step title="Complete setup">
    Click **Add HiBob**. Ravenna validates the credentials, then begins the initial sync of employees and groups.
  </Step>
</Steps>

## What gets synced

* Employee profiles (name, email, job title, department, manager, status, hire date)
* Teams and departments

Data syncs every 24 hours after the initial sync.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed">
    **Cause**: The username (service user ID) or password (token) is incorrect, or the service user has been disabled.

    **Solution**:

    * Verify the ID and token were copied without extra spaces
    * Confirm the service user is still enabled in HiBob
    * Regenerate the token in HiBob if you cannot recover the original value, then update the credentials in Ravenna
  </Accordion>

  <Accordion title="Employees or groups missing">
    **Cause**: The service user's permission group does not grant access to the missing records.

    **Solution**:

    * Open the service user's permission group in HiBob
    * Confirm it includes read access to employees and groups in scope
    * Save the permission group and wait for the next sync, or trigger a manual reconnect
  </Accordion>

  <Accordion title="Create Time-off Request action fails">
    **Cause**: The service user is missing write access to time-off.

    **Solution**:

    * Grant the service user's permission group write access to time-off requests in HiBob
    * Retry the workflow run after the change is saved
  </Accordion>
</AccordionGroup>