At HiBob we are committed to providing a secure and efficient environment for our users to integrate with our services. To enhance our security measures and service reliability, we have made some important changes to our API authentication methods.

Please read through to understand how this may affect your integrations.

What has changed

1. Discontinuation of API Access Tokens: Starting October 31, 2024, we will no longer support the API Access Token method for authentication. We will be moving exclusively to the Service User method, which offers enhanced security and stability for API interactions.
2. Creation of New API Tokens: Effective June 15, 2024, the ability to create new API Access Tokens has been removed from our system interfaces. However, you can still manage existing tokens until October 31, 2024.

Why This Change

This change is part of our ongoing efforts to enhance our security framework and ensure that our services remain robust against evolving security threats. By transitioning to Service User authentication, we aim to provide a more reliable and secure experience for all our users.

The previous method of using API tokens meant that the API access token was linked to a specific employee, and permissions were derived from the permissions of this employee. Service users allows for the separation of permissions between the API and employees, enabling you to better customize the granular permissions that each service user needs.

What You Need to Do

Bob admins should review your current integrations:

• Out-of-the-box Bob integrations:
  If you are using official out-of-the-box Bob integrations (vendor appears in the HiBob Marketplace ↗, this change does not impact you. All official integrations installed via Bob are not affected and no action is required on your side.
• Custom Integrations:
  If you are using any custom Integrations (developed by non-formal vendors or in-house), you may be affected by this change. You need to check whether the implementation is using an API access token based on a specific employee, and if so, you need to switch to service user authentication.

How to check if you are using API Access Tokens

If you are unsure whether you are using any API Access Tokens, review your current access tokens defined in Bob with your IT team:

1. From System Settings > Integrations > REST API, check if you have any API Access Tokens defined.

2. If you don’t have any API Access Tokens defined - you are all set, and you don’t need to do anything.
3. If you have access tokens defined, you will need to review each token with your IT team and verify which integration uses each token. Please consult with the employee who created the token about its current usage and whether it’s being used in an active integration.
4. If the custom integration using the access token was developed by a vendor that is not an official vendor working with Bob ↗, you should contact the relevant vendor regarding migrating to the Basic authorization method.
5. If the custom integration using the access token was developed by your company, contact your IT department or technical focal point in your company regarding migrating to the Basic authorization method in your implementation.
6. Once you verify your custom integration supports the Basic Authorization method, you should Migrate to service users.

Migrate to service users

Step 1: Create a Service User for your integration

Follow the steps in the API Service Users guide to configure the service user and assign the relevant permissions to it based on the integration needs (what data you need to send to the external provider).

As best practice we recommend that you create a dedicated permissions group for each service user, thus assuring it will use only the permissions required for this specific implementation. To learn more, see Create a permission group and add the API service user to it.

Step 2: Replace the authorization method

Once you have set up the service user, you should replace the credentials in your implementations:

• Existing integration configurations: in Bob, from System Settings > Integrations, review your existing integrations in and replace the old api access token credentials with the service user ones in relevant integrations.
• API code implementation: change your code to use the Basic Authentication method and apply the credentials of the Service User. To learn more, see Use the API service user in the authorization header.

Step 3: Revoke existing API Access Tokens

Once you have transitioned to the service user, you should revoke the existing api tokens via the System Settings > Integrations > REST API tile, to ensure this token will not be used anymore.

Support and Assistance

With the discontinuation timeline in mind, we encourage you to adjust your integration setups by the specified dates to avoid any disruptions to your services.

We understand that these changes might require adjustments in your current setup. Our support team is on standby to assist you with any questions or help you might need during this transition. Please do not hesitate to reach out to us at [email protected].

FAQ

How do I make sure that the service user has access to data the same way my access token used to have?

The previous method of using API tokens meant that the API access token was linked to a specific employee, and permissions were derived from the permissions of this employee. Service users allows for the separation of permissions between the API and employees, enabling you to better customize the granular permissions that each service user needs.

To verify the service user has the required permissions. you should map the minimum permissions and create a dedicated permissions group, this is an additional step but it will make things more organized. To learn more, see API Service Users.

What are API Access Tokens?

API Access Tokens used to be managed in Bob via the System Settings > REST API tile. This is an authentication method which is tied to specific users.
The api access tokens are generated based on the permissions of a particular user within the system. The actions that could be performed using this token were limited to the permissions assigned to the user. If the user’s permissions change, the token’s capabilities will also change. These tokens could be revoked if the user was deactivated or their permissions were changed.

What are service users?

Service users are special system accounts created to perform actions via the API and integrations. They are not tied to any individual user but are designed to facilitate system-to-system communication.
Permissions for service users are defined at the time of their creation and remain consistent, independent of individual user roles or changes. They ensure that automated systems can access and manipulate data without being tied to a specific user's account and without requiring additional user licenses.
Service users can be given specific permissions that minimize their access to only what is necessary, enhancing security and are best suited for system integrations where automated, reliable access to the API is required.