HiBob - OAuth migration FAQ
Last updated: October 30, 2026
Overview
HiBob is retiring Service User (basic auth) access for marketplace integrations, so every HiBob connection through Merge must move to OAuth by 31 December 2026. You need your own HiBob OAuth app, approved by HiBob, and each of your customers relinks once. Existing HiBob Linked Accounts keep working until then.
Full setup steps: HiBob - How do I set up partner credentials?
Date | What happens | Existing basic-auth accounts |
|---|---|---|
30 November 2026 | Merge removes Token and user ID from Merge Link. New connections and relinks must use OAuth. | Keep syncing |
31 December 2026 | HiBob turns off basic auth for marketplace integrations. | Show Relink Needed and stop syncing until relinked with OAuth |
The end-to-end path looks like this:
Register as a HiBob Tech Partner.
Create your OAuth app in the HiBob Developer Portal.
Add your development credentials in Merge and test.
Write a user guide and record a demo video.
Submit your app; HiBob reviews it (about two weeks).
Swap in your production credentials.
Ask each customer to relink once.
Terminology
You may see | It means |
|---|---|
Service User, basic auth, legacy auth, Token and user ID | The old method being retired |
OAuth, partner credentials, Use my credentials | Your own HiBob OAuth app, with its credentials saved in Merge |
Development credentials | Work only against your HiBob test company, one at a time |
Production credentials | Issued after HiBob approves your app; work with your customers' live HiBob instances |
Who does what
You own the HiBob app; your customers only re-approve access, and HiBob, not Merge, approves your app.
Party | Does | Doesn't |
|---|---|---|
You (the Merge customer) | Register as a HiBob Tech Partner, create and own the OAuth app, write the user guide, record the demo video, submit for review, enter credentials in Merge, send relinks to your customers | Rely on Merge to create or submit the app |
Your end customer (a HiBob admin) | Opens the relink or Link flow you send and approves HiBob's consent screen | Fill in the Tech Partner form or register with HiBob |
Merge | Hosts the OAuth flow, matches scopes and region settings to your app, can hide Token and user ID on request, relays questions to HiBob | Approve your app, or negotiate or sign HiBob's terms |
HiBob | Reviews and approves your app, issues production credentials, provides your test company | Migrate Linked Accounts |
FAQs
Does this affect us?
Only if your customers connect HiBob through Merge. If they do, production Linked Accounts need action too, not just test ones. If you don't offer HiBob, no action is needed.
Is this a code change?
No. It's configuration: a HiBob app, credentials in the Merge Dashboard, and a relink per customer. You keep using the hibob integration slug, and your customer picks the auth method in Merge Link.
Why is this happening?
It's HiBob's requirement for every Bob Marketplace integration, not a Merge change. HiBob requires each partner to use their own OAuth app.
How do we register as a HiBob Tech Partner?
Fill in HiBob's Tech Partner application form. The last question asks whether you use a Unified API provider; select Merge. Once approved, accept the T&Cs in the HiBob Partner Portal (via PartnerStack) to unlock your Bob test company and the HiBob Developer Portal.
Is there a marketplace fee?
No. The application form mentions a fee, but HiBob has confirmed in writing that it's fully waived for partners onboarding or migrating to the Bob Marketplace, including Merge customers. HiBob doesn't plan to bring it back as a flat annual fee and will give advance notice of any pricing change.
What about the Tech Partner terms?
The terms are between you and HiBob, so Merge can't negotiate or sign them for you. Email [email protected] with "Merge customer" in the subject, or ask your Merge contact to start a thread with HiBob's partnerships team. Raise concerns early so they don't delay your submission.
Will HiBob ask for a security assessment?
Typically only payroll providers are asked for one. If HiBob asks you, let us know.
Setting up your HiBob app
Which scopes does our app need?
Your app's scopes must exactly match what Merge requests, or HiBob returns scopes.mismatch. By default Merge requests these five:
Scope in the Developer Portal | API scope | Needed for |
|---|---|---|
Settings > View company metadata |
| All use cases |
People > View employee data |
| All use cases |
People > View sensitive employee data |
| Sensitive data such as date of birth and SSN |
Time off > View time off |
| Time off data |
Time off > View private time off details |
| Time off balances (older portals call it View employees on private time off) |
Can we request fewer scopes?
Yes. The minimum is View company metadata plus View employee data. With only those two, job title, employment type, start date and termination date still sync, but sensitive fields such as SSN and date of birth don't.
Email [email protected] before you or your customers link, with your scope list and every Merge organization you'll link from (for example dev and prod, or US and EU). We match Merge's request per organization; without that change, your first link fails with scopes.mismatch.
Do custom fields still sync?
Yes. Approved scopes cover current and future data in each category, including custom fields. Your Field Mappings don't change.
Which redirect URI do we add?
Add https://app.merge.dev/oauth/callback under OAuth > Redirect URI. One app can hold both US and EU URIs, so customers with US and EU organizations need only one app.
If your Merge organization is in our EU region, also add https://app-eu.merge.dev/oauth/callback and contact [email protected] before linking so we can enable the EU callback for you. This is a temporary step while we fix a known issue.
What's the landing page URL?
Your own product's URL, usually your login, signup or integrations page. It's where HiBob sends a customer who clicks Install on your marketplace listing. Choose Install from your landing page under Installing your app.
Do we configure webhooks?
No. Leave the webhook endpoint blank. Merge doesn't use HiBob webhooks, and the field doesn't affect HiBob's review.
What goes in the app listing details?
Three gallery images, a value statement and a short description of how the integration works. For integration details use: Integration type API; Direction of data flow From Bob (unless you write back to HiBob through Passthrough); Sync trigger and Sync frequency Scheduled and manual; plus your region and marketplace category.
Where do we enter credentials in Merge?
Merge Dashboard > Integrations > HRIS > HiBob > Set up organization-level credentials. Enter your App ID, development Client ID and Client Secret, and the redirect URI.
Save them in the same Merge organization you test from; otherwise Link only shows the Service User option. Don't remove credentials once added, since that can break link creation for your HiBob customers.
Testing and the demo video
Which HiBob account do we test with?
The Bob test company from your HiBob Partner Portal. Merge's shared HiBob sandbox can't be used for OAuth: HiBob only installs an OAuth app on a company owned by your partner account, so it returns app.owner.required.
In Merge Link, choose Use my credentials > Sandbox data > Development credentials, then sign in with your test company. If you lose access to your test company, contact HiBob through the Partner Portal or let us know and we'll raise it with HiBob.
Will adding credentials affect our live customers?
No. Adding credentials only adds Use my credentials to Link; Token and user ID stays available until 30 November 2026. For a fully separate test environment, sign up for a new Merge organization with a +dev email alias, and we'll upgrade it to match your plan.
Can we use production credentials before approval?
No. Production credentials only work after HiBob approves your app. Until then, test with development credentials and your test company.
We see "App is already installed in DEV mode"
Development credentials link one test company at a time. In the HiBob Developer Portal, open your app's OAuth tab, click Uninstall, then link again.
What must the user guide cover?
HiBob requires a user guide for your customers covering: an overview of the integration, installation steps, setup in your platform, data sync flows, screenshots or short clips, troubleshooting tips and support contact info.
What are the demo video rules?
Show the OAuth flow only. Don't show the Service User or Token and user ID option; HiBob rejects submissions that do.
Record it within 14 days of submitting your app.
Show a visible use for every scope your app requests.
Cover the integration end to end, per HiBob's video requirements.
We can hide Token and user ID in Link for your organization while you record.
Review, approval and production credentials
How long does HiBob's review take?
About two weeks end to end in our experience, so submit well before 30 November 2026. HiBob may come back with listing feedback, for example an app icon smaller than 160×160 px. If a review seems stuck, tell us and we'll follow up with our HiBob contact.
How do we submit?
In the HiBob Developer Portal, open your app's Submission information page, add the URLs for your integration demo video and user guide, and save. Then click Submit for review.
What do we do after approval?
In the HiBob Developer Portal, open your app's OAuth section and copy the production Client ID and Client Secret.
In the Merge Dashboard, go to Integrations > HRIS > HiBob and click Edit.
Replace the development Client ID and Secret with the production ones. Keep the same App ID and redirect URI (
https://app-eu.merge.dev/oauth/callbackfor EU organizations).Save. Don't remove the credentials afterwards.
With production credentials saved, you can only link live HiBob instances, not your test company. If you use separate Merge organizations for dev and prod, or US and EU, and asked us to match fewer scopes, tell us before linking in each organization.
Moving existing customers
Each of your HiBob customers relinks once before 31 December 2026; relinking the existing Linked Account keeps everything except the auth method. There's no bulk switch.
Will relinking keep our Linked Accounts?
Yes, if you relink the existing Linked Account rather than create a new one. The account token, Linked Account ID, record IDs (including Employee id and remote_id), synced data, Remote Data and Field Mappings stay the same.
How you relink | Result |
|---|---|
Relink flow with | Same Linked Account and token |
Magic Link with the same | Same Linked Account and token |
New | New Linked Account and token |
Deleting the Linked Account first | New Linked Account; the old one's data and credentials are cleared |
What does our customer see?
A HiBob admin opens your relink or Magic Link, chooses Use my credentials > Production data, and approves HiBob's consent screen. That's all they do.
What if a customer doesn't relink in time?
From 30 November 2026, OAuth is the only relink option. After 31 December 2026, Linked Accounts that haven't been relinked show Relink Needed and stop syncing until relinked with OAuth.
Can we see which accounts have migrated?
Not yet. There's no dashboard view or API field for auth method today, so track relinks on your side. We can check specific Linked Accounts on request.
Troubleshooting
Error or symptom | Likely cause | What to do |
|---|---|---|
| Your app's scopes differ from what Merge requests | Add all five scopes to your app, or ask us to match your set for that organization, then relink |
| Testing on a HiBob company your partner account doesn't own | Test with your own Partner Portal test company |
| Wrong App ID, Client ID or Secret, or credentials saved in another organization | Check the credentials and the organization they're saved in |
| Development credentials already linked to your test company | Uninstall on your app's OAuth tab in the HiBob Developer Portal, then relink |
Link only shows the Service User / Token and user ID screen | No credentials saved in this organization | Save credentials in the organization you're linking from |
Link token creation fails with HTTP 400 "necessary configuration work" | Credentials were added and then removed | Contact support to reset your configuration |
Error on the callback page after consent (EU organization) | EU redirect not set up | Add the |
Stuck on Awaiting authorization, or the Linked Account stays Incomplete | Usually scopes, redirect URI or the wrong test company | Check those three, then contact support with the details below |
Getting help
Contact your CSM or [email protected]. To speed things up, include:
Your Merge organization name (and region, US or EU)
The Linked Account ID, if one exists
The scopes on your HiBob app
A screenshot of the error
For questions about HiBob's partner program, terms or review, email [email protected] with "Merge customer" in the subject.