Getting started with OAuth app integrations

OAuth 2.0 is now supported as a secure alternative to Service Users for third-party integrations. Instead of creating service users and assigning permission groups manually, customers can now install apps that request specific permissions (scopes) during installation.

This guide explains:

How developers can integrate their app with HiBob using OAuth 2.0
What customers see when installing an app, and how to select permissions

How OAuth works

HiBob uses the OAuth 2.0 Authorization Code flow.

🚧
Mandatory Marketplace-first flow

Apps listed in the HiBob Marketplace must support installation that starts from Bob.

Starting installation from your app is optional, and should be treated as an additional convenience flow.

Here’s the high-level process:

Customer installs your app from Bob’s Marketplace. Optionally, you can support installation starting from your app.
User consents in Bob - the customer approves the scopes and selects the audience (which employees your app can access). See Scopes and people data access for details.
Bob calls you redirect_uri (callback endpoint) - to perform token exchange. The redirect_uri endpoint/page must succeed even if the customer is not authenticated in the you app yet.
Your app can now access the API.
Token Rotation – when the access token expires, refresh it using the refresh_token.

🚧
Note: During the authorization process, Bob will automatically subscribe the client to the required webhooks configured for the app, if any.

Sequence diagram

When starting from Bob (mandatory flow)

sequenceDiagram
    participant App as Partner App
    participant OAuth as HiBob OAuth API
    participant API as HiBob API

    Note over OAuth: Customer clicks "Install" in HiBob (marketplace / in-product)
		OAuth->>OAuth: Consent
    OAuth-->>App: Redirect to registered redirect_uri with authorization code (require login to app)

    App->>OAuth: Exchange code for tokens (client_id + client_secret)
    OAuth-->>App: Return access_token + refresh_token

    App->>API: Call APIs with access_token
    API-->>App: Return data

    alt Access token expired
        App->>OAuth: Refresh token
        OAuth-->>App: New access_token
    end

When starting from your app (optional flow)

sequenceDiagram
    participant App as Partner App
    participant OAuth as HiBob OAuth API
    participant API as HiBob API

    Note over App: Customer clicks "Install" in the App
    App->>OAuth: Redirect user to install URL with app_id, scopes, redirect_uri, and state (optional)
		OAuth->>OAuth: Consent
    OAuth-->>App: Redirect back with authorization code, and state (optional, only if provided)

    App->>OAuth: Exchange code for tokens (client_id + client_secret)
    OAuth-->>App: Return access_token + refresh_token

    App->>API: Call APIs with access_token
    API-->>App: Return data

    alt Access token expired
        App->>OAuth: Refresh token
        OAuth-->>App: New access_token
    end

Scopes and people data access

HiBob utilizes a multi-layered authorization model to ensure strict data privacy and compliance. When a customer installs your app, they are presented with two distinct configuration gates:

Scopes: The customer must first consent to the App permissions (scopes) you defined in the Developer Portal. These determine what categories of data your app can access (e.g., Attendance policies and data, Employee data, or Sensitive historical data).
Audience access restrictions (People data access): The customer then defines the Audience. This determines the specific population of employees your app is permitted to interact with. The user chooses one of three modes:
- All company: Grants access to the entire organization.
- Select by condition: Limits access to employees matching specific details (e.g., Site equals Germany).
- Select by name: Grants access only to specific, hand-picked individuals.

📘
Why we use audience restriction
HiBob uses a two-tier authorization model (Scopes + Audience) to ensure:

Compliance: Allows admins to restrict data by geography or department to meet GDPR and data residency requirements.

Least Privilege: Limits app access to only the necessary employee population rather than the entire global workforce, for example, only employee in the Germany site.

Risk Mitigation: Isolates data exposure, ensuring that a credential compromise only affects the permitted subset of data.

Known limitations

Updating app permissions (re-consent) is not supported. Uninstall and reinstall is required

Build your integration

Step 1. Map required scopes and webhooks

Use the Scopes mapping to endpoints to identify the minimum set of permissions (scopes) your application requires.
From the available webhook events, identify the webhook events your integration needs.

Step 2. Create your app

Follow the instructions in Add and submit an app.
You will be required to provide:
- Your list of required scopes
- Your redirect_uri (callback endpoint)
You will receive:
- client_id (developer credentials)
- client_secret (developer credentials)
- App installation URL (dynamically created based on the app-id, redirect_uri and scopes)

Step 3 (Optional): Start installation from your app

🚧
Notes:

You app must support installation that starts from Bob. starting the installation from your app is optional and requires .

When testing with developer credentials, you need to add a query param: mode=dev to the installation URL.

When using in production the App installation URL already includes the parameters you need in order to install your app.

To redirect the customer’s web browser to the OAuth server:

Copy the App Installation URL link from the OAuth section in the developer portal (see step 2).
Call the App installation URL:

GET <App installation URL>
?app_id=<app-id>
&scope=<space-separated-list-of-scopes>
&redirect_uri=<redirect-url>
&state=<state>
&mode=dev  // only for testing with developer credentials

The request must provide the following query parameters:

Query parameter	Required	Description
`app_id`	Yes	unique application identifier provided to you when registering the app by HiBob
`scopes`	Yes	A list of scopes provided by HiBob.
`redirect_uri`	Yes	Your callback endpoint that will handle the authorization code exchange. An authorization code will be sent to that URL if a user approves the app install. Or, if a customer declines, the corresponding error will also be sent to this URL.
`state`	No	You may pass any random string as the state parameter and the same string will be returned to your app after a user authorizes access. It may be used to store the user’s session ID from your app or distinguish different responses. Using state may increase security; see RFC-6749. Always validate it when you receive.
`mode`	Only in dev mode	If provided, value must be `mode=dev`. Required only when working with `developer credentails` and testing before production.

Step 4: Implement your callback URL endpoint

After the customer accepts or denies your app installation in HiBob, the browser will be redirected to your callback URL (which was registered with the app):

GET https://yourapp.com/callback
?code=<authorization-code>
&state=<RANDOM_STATE_STRING>

The following query parameters will be passed to the request:

Query parameter	Description
code	The authorization code that was issued when the user agreed to the installation, or the error code if the user denied installation.
state	The same value will be returned to your callback URL if the state was provided during the authorization request.

🚧
Callback URI Implementation notes

Your redirect_uri must work for users who are not logged in yet. Do not assume an existing session on your side when Bob redirects back after consent.

The authorization code is short-lived, so the callback should be designed to handle login without breaking the flow.

Recommended flow: to handle short-lived code, exchange the code server-side immediately, store the resulting tokens temporarily keyed by state, then prompt the user to log in or create an account, and finally link the stored tokens to the user’s tenant/account.

Make sure you follow Token management best practices. This helps ensure your integration remains secure and reliable over time.

Step 5: Exchange code for tokens

After the customer confirms the app installation, you will need to exchange the authorization code with a pair of access and refresh tokens. An access token allows you to access the public API.

🚧
Note that the authorization_code expires after 5 minutes.

To exchange the authorization_code for the tokens, you must execute this HTTP request to the OAuth server:

Basic Auth Header(recommended)
POST https://auth.app.hibob.com/oauth2/v1/apps/token
  -H "Content-Type: application/x-www-form-urlencoded"
  -H "Authorization: Basic BASE64_ENCODE(<CLIENT_ID>:<CLIENT_SECRET>)"
  -d "grant_type=authorization_code"
  -d "code=<AUTHORIZATION_CODE>"
  -d "redirect_uri=https://yourapp.com/callback"

OR
POST https://auth.app.hibob.com/oauth2/v1/apps/token
  -H "Content-Type: application/x-www-form-urlencoded"
  -d "grant_type=authorization_code"
  -d "client_id=<CLIENT_ID>"
  -d "client_secret=<CLIENT_SECRET>"
  -d "code=<AUTHORIZATION_CODE>"
  -d "redirect_uri=https://yourapp.com/callback"

The content-type for the request must be application/x-www-form-urlencoded.

To execute the request, we recomment that your request will be authenticated via HTTP Basic Auth with the values of the client_id and the client_secret you obtained in step 2.

Body Parameter	Description
`grant_type`	Since you are trying to exchange an authorization code for a pair of tokens, you must use the value "authorization_code".
`code`	The authorization code that you received after the user confirmed app installation.
`redirect_uri`	The callback URL you provided when you registered your app.
`client_id`	The application’s client ID (provided during app registration by HiBob); note: this is different from the `app_id` in the installation URL
`client_secret`	A secret of the application provided by HiBob

If all data is correct, you will receive a response with the JSON data:

  {
    "access_token": "eyJhbGciOiJIUz...",
    "token_type": "Bearer",
    "expires_in": 3003600,
    "refresh_token": "abc123eyJhbG...",
    "id_token": "eyJhbGciOiJIUz..."
  }

JSON key name	Description
access_token	You need to use an access token to access the data via API and it expires quickly (5 minutes). You will need to refresh the access token if the `access_token` becomes invalid.
token_type	The format of the token. Always "bearer".
expires_in	The maximum time in seconds until the access_token expires.
refresh_token	A refresh token is needed when you refresh the access token. refresh_token will expire if it isn't used in 60 days. Each time refresh_token is used, its expiry date is reset back to 60 days.
id_token	Internal provider ID (can be ignored).

🚧
Notes:

Securely store the access_token and refresh_token associated with the companyId (available as a custom claim within the access token). Mapping tokens to companyId ensures you use the appropriate access token for the relevant company.

Prepare webhook listener endpoint. This endpoint will be responsible for receiving and processing event notifications from our system for all the companies you manage. To learn more, see Partner webhooks delivery.

Step 6: Using the tokens to call the Public API

Once you receive an access token, you can call HiBob Public APIs that support OAuth. These requests must include the Authorization header with Bearer token.

METHOD

https://api.hibob.com/v1/....
  -H "Authorization: Bearer <valid-access-token>"

Testing from the Public API reference

Calling the Public API with Try It!

Before developing your code, you may want to test the endpoints from our API reference, using the Try it! option. To do this, you can create the token from Postman, and then paste the token into Try It!'s Bearer authorization header to test the endpoints here.

To get a token and test in Try It!

Register your app in the Developer Portal and set the redirect URL for Postman to https://oauth.pstmn.io/v1/callback.
Complete the OAuth flow in Postman:
- Create an OAuth 2.0 request.
- Copy the installation URL from the Developer Portal into the Auth URL in Postman and add &mode=dev.
- Set Client ID and Client Secret.
- Get a token. This will log you in to Bob, display the consent screen, and then redirect back to Postman.
- Copy the token from Postman.
Paste the token in Try It!:
- Select Bearer in the auth type.
- Paste the token.
- You can now call the endpoints from Try It! to test.
- If the token expired, refresh it in Postman and copy again.

Redirect URL: Must match what you registered. For Postman use https://oauth.pstmn.io/v1/callback.

Step 7: Implement refresh flow

Access tokens expire after 5 minutes. Use the refresh token to call the HiBob token refresh endpoint before expiry to ensure your app continues to work seamlessly. Also, ensure you have a refresh flow, so customers won't need to reinstall your app frequently.

To obtain a valid access token, refresh the tokens periodically:

POST

https://auth.app.hibob.com/oauth2/v1/apps/token
  -H "Content-Type: application/x-www-form-urlencoded"
  -d "grant_type=refresh_token"
  -d "client_id=<CLIENT_ID>"
  -d "client_secret=<CLIENT_SECRET>"
  -d "refresh_token=<VALID_REFRESH_TOKEN>"

Parameter
`grant_type`	Should always be `refresh_token`
`client_id`	The application’s client ID (provided during app registration); this is not the same as the `app_id` in the installation URL
`client_secret`	The application’s secret
`refresh_token`	A valid refresh token obtained during the authorization code exchange or a previous refresh

Response from auth refresh:

  {
    "access_token": "eyJhbGciOiJIUz...",
    "token_type": "Bearer",
    "expires_in": 360000,
    "refresh_token": "abc123eyJhbG...",
    "id_token": "eyJhbGciOiJIUz..."
  }

Step 8: Uninstall an app (during development only)

🚧
Important notes

This uninstall method is a solution for development and early access testing only.

In production, your customers will uninstall apps directly from the Bob Marketplace UI, without using this API call.

During development, uninstalling an app should be done via an API call. Use the API call to uninstall when:

You are testing your app in development mode with developer credentials.
You need to remove an existing development installation before reinstalling or updating it.

To uninstall an app, use Postman or a similar tool with the following DELETE request:

DELETE 'https://app.hibob.com/api/marketplace/apps/{app_id}/installations/{installation_id}' \
  --header 'cookie: hibob=<hibob-cookie>'

Parameters

Parameter

Description

app_id

The ID of the app as shown in the Developer Portal.

installation_id

To get the ID of the specific installation you want to remove:

First, try installing the (already installed) app in dev mode.
Fetch the installationId from the error message - see screenshot below.

hibob-cookie

Copy your Bob cookies from the browser DevTools while you are logged into Bob: open DevTools > Application tab > Storage > expand Cookies > select hibob’s app path > copy the hibob cookie value.
Add it to the request headers in Postman: Key: Cookie, Value: hibob=<copied_cookie_value>

Developer Best Practices

Scopes and audience restrictions best practices

Because the People data access layer in Bob acts as a filter on top of your scopes, your application must be built to handle the possibility of restricted data sets:

Handle partial results: A request to list employees may return a subset of the total number of employees. Never assume a successful API response contains the full organization.
Expect "Not Found" errors: If you attempt to access a specific employee profile via ID that falls outside the selected audience, the API will return a 404 Not Found (or 403 Forbidden), even if your scopes are valid. Never assume the employee will still exist because it may be removed from the selected audience (e.g. moved to another department).
Immutable configuration: The audience selection is locked upon authorization. To modify the target population (e.g., to move from "UK Employees" to "All company"), the customer must uninstall and reinstall the application.

📘
In your documentation, recommend to the user what are the specific People data access setting required for your app to function correctly (e.g., "To provide accurate payroll reporting, please select 'All company' during the HiBob authorization flow.").

Token management best practices

When integrating with HiBob, you’ll receive both access tokens and refresh tokens during the consent flow (when a company installs your application). To ensure your application works reliably for all of your customers, follow these best practices for storing and refreshing tokens.

Persist tokens with respect to the company identifier

Your application may be installed by multiple companies. To avoid mixing up tokens, you should always store the tokens alongside the HiBob companyId that issued them.

The companyId is included as a custom claim in the access token.
You should persist both the access token and the refresh token together with the corresponding companyId.
Whenever you need to call HiBob’s API on behalf of a company, select the access token associated with that company’s ID.

This ensures your application reliably associates each company with its correct set of tokens.

Refresh tokens according to their lifetime

HiBob issues tokens with strict lifetimes:

Access token: Valid for 5 minutes. The issued and expiration timestamps are embedded in the token, so you can check whether it’s still valid before making a request.
Refresh token: Valid for 30 days. Like the access token, it contains issued and expiration timestamps.

To maintain uninterrupted access:

Refresh your tokens regularly and at least once every 30 days.
If a refresh token expires, you cannot get new tokens for that company. In that case, your user (the HiBob customer) would need to repeat the consent flow to reinstall your app. This creates unnecessary friction and disrupts the user experience.

👍
By proactively refreshing tokens, you ensure your users always have a seamless connection to HiBob through your application.

Token Refresh Flow

Check whether the access token has expired before each API call, and refresh it if necessary.
Set up a background job that refreshes tokens periodically, at least once every 30 days (the lifetime of a refresh token)

sequenceDiagram
    participant PartnerBE
    participant HiBobAPI
    participant HiBobAuthAPI

    PartnerBE->>PartnerBE: Identify need to call HiBob
    PartnerBE->>PartnerBE: Select access token by HiBob company ID
    PartnerBE->>PartnerBE: Check if token is expired
    alt Token is expired
        PartnerBE->>HiBobAuthAPI: Call refresh API with refresh token
        HiBobAuthAPI-->>PartnerBE: Return new access + refresh tokens
        PartnerBE->>PartnerBE: Store new tokens in storage
    end
    PartnerBE->>HiBobAPI: Call HiBob API with access token

    Note over PartnerBE: Periodic background process
    PartnerBE->>PartnerBE: Check if refresh token is about to expire e.g. (age > 28 days)
    alt Refresh old tokens 
        PartnerBE->>HiBobAuthAPI: Proactively refresh tokens
        HiBobAuthAPI-->>PartnerBE: Return new access + refresh tokens
        PartnerBE->>PartnerBE: Store new tokens in storage
    end

How to handle compromised tokens

If an access token, refresh token, or your client secret is ever exposed, you must act immediately to protect your users and notify HiBob.

⚠️
Important:

A compromised access token or refresh token only affects the single customer company that installed your app.

A compromised client secret affects all companies that installed your app, since it identifies your entire integration.

Access token compromised

Access tokens are short-lived (≈5 minutes), which limits the potential damage.
Still, contact HiBob immediately at partnersupport@hibob.io, and include your App ID and details of the incident.
The affected customer must go through the consent flow again to restore access.

Refresh token compromised

Refresh tokens are valid for up to 30 days, so a compromise carries more risk.
Contact HiBob immediately at partnersupport@hibob.io, and include your App ID and details of the incident.
The affected customer must go through the consent flow again to restore access.

Client secret compromised (critical)

The client secret identifies your entire integration. If compromised, it can impact all companies that use your app.
Contact HiBob immediately at partnersupport@hibob.io, and include your App ID and details of the incident.
Rotate your client secret in the Developer Portal. All previously issued refresh tokens will become invalid.
All customers must go through the consent flow again to reinstall your app once the new secret is issued.