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

**1. Open HiBob settings**

Log in to HiBob and go to **Settings > Integrations > Service users**.

**2. 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

**3. 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.

### Add the integration in Ravenna

**1. Navigate to integrations**

Go to **Settings > Integrations** and find **HiBob** in the HRIS section.

**2. Select Basic Authentication**

Click **Connect**, then select **Basic Authentication** as your authentication method.

**3. Enter credentials**

Provide the values from your HiBob service user:

**username** `string` *required*

The HiBob service user ID.

**password** `string` *required*

The HiBob service user token.

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

**4. Complete setup**

Click **Add HiBob**. Ravenna validates the credentials, then begins the initial sync of employees and groups.

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

> [accordion] 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] 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] 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


## Related topics

- [Setup](https://docs.ravenna.ai/integrations/okta/setup/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.