Creating API service users

API service users in Bob allow you to access APIs in Bob. Multiple service users can be created, each with unique permissions, depending on the API you want to access.

Note: Service users are detached from any actual employee and are have only the credentials required for the API access. Service users cannot "log in" to Bob and are used only for the HiBob public API.

Follow these steps to start using Bob's API:

1. Step 1: create a new API service user, which will provide the ID and Token necessary for authorization.
2. Step 2: Create a permission group and add the API service user to it.
3. Step 3: Set permissions to the permissions group.
4. Step 4: Test the API using the service user's ID and token.
5. Step 5: Use the API service user in the authorization header to include the service user’s ID and Token.

Step 1: Create a new API service user

The API service user is created and managed in the service users configuration in Bob.

1. If you have direct access to Bob: create a service user in the service users configuration page, and collect the ID and Token. For step-by-step instructions, see Manage service users ↗.
2. If you don't have direct access to Bob: request the ID and Token from the Bob Admin.

Later, when you want to access the API via HTTP, you will need to use the ID and token for the HTTP authorization header.

Step 2: Create a permission group and add the API service user to it

API service users in Bob have no access permissions by default.

When using the Bob API, each endpoint may require different permissions depending on the data you need to access. For example, accessing time off data requires different permissions than accessing an employee’s work history, and accessing job ads from your careers page does not require any special permissions.

As a best practice, to assign permissions to an API service user, you should add it to a dedicated permissions group. This group should include only the permissions required for the API actions you plan to perform with this service user.

To work with permission groups:

1. If you have direct access to Bob: Create a service user permission group ↗ and link the service user to this group.
2. If you don't have direct access to Bob: request the Bob Admin to create the permission group.

Step 3: Set permissions to the permissions group

A new permissions group has all permissions disabled by default, requiring you to explicitly choose which permissions to include or exclude. Consult with the Bob Admin to determine the necessary permissions for each service user.

📘

Notes:

1. Ask Bob Admin: If you don't have direct access to Bob, request a Bob Admin to define the service user and permissions based on the data you want to access via the API. Bob Admins can also view the assigned permissions per service user. To learn more, see Manage service users.
2. Default employee data permissions: To access basic employee data (fields located in the 'root' (basic info), 'about', 'employment', and 'work' categories), you should grant Permissions for Default Employee Fields in People Search API ↗. This will allow you to read the default fields being returned from the People Search Public API, when no field is specified in the search query.

The permissions are split into three categories:

3.1 Features

Grant access to Bob features you need to access via the API you plan to use with this service user. For example, if you want to access reports, you may need to activate some options in Features > Reports.

1. From the top right, click Edit.
2. Select the area of Bob you'd like to manage.
3. Mark the checkbox(es) to enable or disable the permissions you’d like to give the service users in this group.

3.2 People’s data

Grant access to people’s data in each area of Bob for the API you plan to use with this service user.

1. From the top right, click Edit.
2. Select the area of Bob you'd like to manage.
3. Mark the checkbox(es) to enable or disable the permissions you’d like to give the service users in this group.

📘

'View', 'edit' and 'view history'

To access Employee data via the API you need to grant basic view access to each category:

• View all employees' sections

If you want to access history data (such as all the entries in the Lifecycle or Work table), you need to also grant the the history access:

• View all employees' section histories.

If you want to update data or access sensitive data that requires an extra layer of permissions, you need to grant the edit permission:

• Edit all employees' sections

3.3 Access rights

Grant access to the people whose data you want to access via the API you plan to use with this service user..

1. From the People’s data tab, click Access rights.
2. Select whose data these permissions apply to (by default, the access rights are set to all employees using the Lifecycle status equals Any condition). Options are:
   • Everyone: all employees marked as Employed in the system.
   • Select people by condition: click Edit, select conditions from the dropdown menu, then click Apply.
   • Select people by name: click Edit, select specific employees, then click Apply.

To learn more, see Create and update a service user permission group ↗.

To learn more about which permissions each API endpoint requires, see the different endpoints in the API reference guide.

Step 4: Test the API

You can test the API using Postman or directly from the 'Try It!' option from the interactive API reference guide.

To test the endpoint, you should first locate it in Bob’s reference guide and set the service user's credentials.

For step-by-step instructions, see how to Test endpoints.

Step 5: Use the API service user in the authorization header

When you send the HTTP requests to call Bob’s API, you need to include an authorization header:

• The authentication details you must include in the header are the service user’s ID and Token.
• The authentication methods must be basic access authentication.

Using Basic access authentication in the authorization header:

1. Form the credentials: Combine your service user ID and token into a single string, separated by a colon (:).

 SERVICE-USER-ID:TOKEN

2. Encode: Encode this combined string using Base64 encoding. The resulting string is your credentials in Base64 format.

Base64.encode(SERVICE-USER-ID:Qe8q89RwbzeS7mmhMcAsN1crM73m6MdbjewGCCUY)

Note: This sample is not specific to a single programming language. 
It represents a conceptual example of encoding a string using Base64 encoding.

Set the Authorization Header: Include an HTTP header field in your request in the form of:

authorization: Basic <Base64-encoded credentials>

Note: The method to perform Base64 encoding varies between programming languages. Consult the documentation for your specific language or ask your development team for details on how to encode the credentials.

Frequently asked questions

How can I remove an API service user?

You can remove an API service user. However, be aware that if your code uses this API service user to access Bob’s API, it will stop functioning. You'll need to update your code to use a different service user.

To remove an API service user, follow these steps.

How can I find the API service user’s token?

You can only access the service user’s token during the generation stage, so make sure to copy and save it then. If you lose the token, you can generate a new one, invalidating the old token. You must update all instances where the old token was used with the new token.

To refresh the service user’s token follow these steps.

How can I see the permissions assigned to a service user?

The Service Users table in Bob lists the service users you have defined, the assigned permission groups, and the assigned permissions.

You can view the assigned permissions and permission groups, view the last usage details for this service user and export the list, including the permissions, to a .csv or .xlsx file.

To learn more, see View the assigned permission and permission groups.