> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/people-management/migrating-hibob-to-oauth.md). # Migrating HiBob to OAuth Move your HiBob connection from the legacy service-user integration to the Bob Marketplace app, and point your agents at the new connection Harmony offers two ways to connect Bob. The legacy **HiBob** integration uses a Service User ID and token that you paste into Harmony. The newer **HiBob (OAuth)** integration connects through the Harmony app in the Bob Marketplace, where a Bob admin authorizes the connection with a single consent screen. This guide walks you through moving a workspace from the legacy connection to HiBob (OAuth), including how to migrate custom agents that use HiBob blocks and when it is safe to disconnect the old integration. ### Why the connection is changing HiBob now requires every app in the [Bob Marketplace](https://www.hibob.com/marketplace) to authenticate with OAuth 2.0, and no longer permits Marketplace integrations that rely on a Service User ID and token. To comply, Harmony's HiBob integration is now delivered as the [Harmony app in the Bob Marketplace](https://www.hibob.com/marketplace/3F7QURUP33/overview), which uses OAuth. The new connection is documented on the [HiBob (OAuth)](https://docs.harmony.io/integrations/hris/hibob-oauth) integration page. For you, the switch means: * **No tokens to manage** - you authorize once in Bob instead of creating a service user and copying its ID and token into Harmony. * **Permissions reviewed in Bob** - the install screen lists exactly what Harmony is requesting, and you approve it there. * **No stored credentials** - Harmony never stores your HiBob credentials. Everything you use today keeps working after the switch: employee sync, onboarding and offboarding agents, HiBob blocks in custom agents, and time-off requests through the Harmony agent. ### Who can perform the migration {% hint style="warning" %} **The reconnect must be completed end to end by a single user who is both a Bob admin and a Harmony admin.** That user clicks **Connect** in Harmony's settings, is redirected to Bob, signs in there, installs the Harmony app, and grants its permissions. The flow cannot be split between two people, and it fails if the user who starts it in Harmony is not also an admin in Bob. If no one on your team holds both roles today, grant one before you start. {% endhint %} | Role | What it is needed for | | ------------- | ------------------------------------------------------------------------------ | | Bob admin | Installs the Harmony app from the Bob Marketplace and approves its permissions | | Harmony admin | Starts the connection from **Settings** > **Integrations** and updates agents | The reconnect itself takes a few minutes. ### Step 1: Connect HiBob (OAuth) in Harmony 1. Log in to your Harmony dashboard. 2. Go to **Settings** > **Integrations**. 3. Find **HiBob (OAuth)** under **HRIS** and click the card. 4. Click **Connect**. You can connect HiBob (OAuth) while the legacy HiBob integration is still connected. Both connections can exist side by side until you finish the migration. ### Step 2: Authorize in Bob Harmony redirects you to Bob. Sign in with your **Bob admin account** if prompted. 1. Review the permissions Harmony is requesting. Each one is explained under [Permissions Explained](https://docs.harmony.io/integrations/hris/hibob-oauth#permissions-explained) on the integration page. 2. Under **People data access**, select **All company**. Harmony's employee directory, routing, and offboarding automations rely on seeing the whole organization. See [Choosing People data access](https://docs.harmony.io/integrations/hris/hibob-oauth#choosing-people-data-access). 3. Click **Authorize**. Bob returns you to Harmony. {% hint style="info" %} Bob locks permissions and People data access at authorization time. If you need to change either one later, uninstall the Harmony app in Bob and connect again. {% endhint %} ### Step 3: Confirm the connection Back in Harmony, open **Settings** > **Integrations** and confirm that **HiBob (OAuth)** shows a **Connected** status. Harmony receives and stores the authorization automatically. No further configuration is needed, and the first employee sync starts on its own. ### Step 4: Move your agents to the new connection If you have custom agents that use HiBob blocks, each block is pinned to a specific HiBob connection. Blocks pinned to the legacy connection keep using it until you change them. For each custom agent that uses HiBob blocks: 1. Open **Agents** from the left sidebar in Harmony. 2. Click the agent to open it in the Agent Builder. 3. Click each HiBob block and, in its properties panel, change the connection to **HiBob (OAuth)**. 4. Save the agent. The same HiBob blocks work with both connections. Only the selected connection changes, so the block's inputs and outputs stay as they are. The built-in **Time Off Request** and **HRIS to IDP Sync** agents also work with HiBob (OAuth). Select the new connection in each agent's settings. {% hint style="info" %} Prefer to have Harmony handle this step? Once Step 3 is done, reach out through any of the channels under [Getting help](#getting-help). We will migrate your agents and remove the legacy connection for you. {% endhint %} ### Step 5: Disconnect the legacy HiBob integration Only after the new connection is live and every agent has been moved: 1. Go to **Settings** > **Integrations**. 2. Open the legacy **HiBob** card. 3. Click **Disconnect** and confirm. {% hint style="warning" %} HiBob blocks still pointing at the legacy connection fail once that connection is removed. Finish Step 4 before Step 5. {% endhint %} Once the legacy integration is disconnected, you can also remove the Harmony service user in Bob under **Settings** > **People** > **Service users**. It is no longer used. ### Getting help If anything is unclear, you hit an error during the reconnect, or you would like us to walk you through it live, reach out on whichever channel is easiest for you: * **In-app chat** - click **Help** at the bottom of the left sidebar in Harmony to open a chat with our team. * **Slack** - post in your shared Slack Connect channel with Harmony. Our team monitors it and will pick it up right away. * **Microsoft Teams** - message us in your shared Teams channel with Harmony. * **Email** - write to . Don't have a shared Slack or Teams channel with us yet? Ask through the in-app chat or email and we will set one up for you. ### Frequently Asked Questions **Will employee sync stop while I migrate?** No. The legacy connection keeps syncing until you disconnect it, and HiBob (OAuth) starts syncing as soon as it is connected. Running both for a short time is expected. **What happens if the admin who authorized the connection leaves the company?** Nothing. The authorization is not tied to that admin's personal session. It stays active until the Harmony app is uninstalled in Bob or the integration is disconnected in Harmony. **I selected "Select by condition" or "Select by name" for People data access. Can I change it?** Not on the existing installation. Uninstall the Harmony app in Bob, then connect again from Harmony and choose **All company**. **An agent step fails with "HiBob integration not found". What does it mean?** The block is pinned to a HiBob connection that has been disconnected. Open the agent from **Agents** in the sidebar, click the block, and select **HiBob (OAuth)** as its connection. **Can I skip the legacy disconnect and leave both connected?** You can, but the legacy connection will stop working when HiBob retires service-user access for Marketplace apps. Completing Step 5 on your own schedule avoids an unplanned failure later. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.harmony.io/people-management/migrating-hibob-to-oauth.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.