📘

OAuth 2.0 app integrations are available for approved HiBob Marketplace and technology partners only.

This guide is intended for partners building apps that connect multiple customer tenants to Bob through the HiBob Marketplace. For customer-built integrations, continue using Service Users for authentication.

Getting started with OAuth app integrations

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

This guide explains:

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

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:

1. Customer installs your app from Bob’s Marketplace. Optionally, you can support installation starting from your app.

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

3. Bob calls you at redirect_uri (callback endpoint) to perform the token exchange. The redirect_uri endpoint/page must succeed even if the customer is not yet authenticated in your app.

4. Your app can now access the API.

5. 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:

1. 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).

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

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

Step 2. Create your app

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

Step 3: Implement your callback URI 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:

🚧

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 4: 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.

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..."
  }

🚧

Notes:

1. 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.
2. 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 5: Test installation from Bob's marketplace

To test your app installation from the Bob marketplace, as a user would, use the install button in the Developer Portal.

1. In the developer portal, open your app's details.
2. From OAuth, scroll to Test your app installation.
3. From Test from Bob Marketplace, click Install.
4. This will open Bob's consent screen and then redirect to your redirect URI.

Step 6: (Optional) Start installation from your app

To test starting the installation from your app or from tools like Postman, follow these instructions.

🚧

Notes:

1. Starting the installation from your app/marketplace is optional.
2. First, your app must support installation that starts from Bob Marketplace.
3. When testing installation with developer credentials, use the App installation URL for testing.
4. When using in production use the App installation URL from the Production Credentials section.

1. When testing, use the App Installation URL for testing from the Test your app installation section in the developer portal. When in production, switch to the final App Installation URL from the Production Credentials section.
2. The installation URL already includes the scopes, redirect_uri, and app_id you configure in the developer portal.
3. Call the App installation URL.
4. This will open Bob's consent screen and then redirect to your redirect URI.

Call the App installation URL for testing:

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

The request must provide the following query parameters:

Step 7: 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

📘

OAuth 2.0 app integrations are currently available for approved HiBob Marketplace and technology partners only.

For customer-built integrations, continue using Service Users for authentication.

Step 8: 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>"

Response from auth refresh:

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

Step 9: Uninstall an app (during development only)

🚧

Important notes

• This uninstall method is a solution for development and early access testing only, when testing with Developer Credentials.
• Use the Uninstall button when you need to remove an existing development installation before reinstalling or updating it.
• Uninstall will work both for apps installed using the Install button in the developer portal, or using the App installation URL for testing.
• In production, your customers will uninstall apps directly from the Bob Marketplace UI, without using this method.

During development, installing and uninstalling an app should be done via the developer portal:

1. From the Developer Portal, open your app details.
2. To uninstall, from OAuth, click Test your app installation > Uninstall.
3. To reinstall, click Test your app installation > Install

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

1. Check whether the access token has expired before each API call, and refresh it if necessary.
2. 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 [email protected], 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 [email protected], 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 [email protected], 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.

Troubleshooting