title	description	updated_date
HiBob API	How to create and use service user credentials for HiBob API authentication.	2025-10-24T16:45:21Z

What we need

[] API Token [] Username / User ID

Authentication

HiBob uses service user credentials for authentication. This guide will walk you through the process of creating a service user and using the credentials for HiBob API access.

Prerequisites

You must have an admin account in HiBob
You need access to create and manage API service users

Creating a Service User

Log in to your HiBob account
- Visit the HiBob website and sign in with your admin credentials.
- Make sure you have the necessary permissions to create service users.
Access the API service users section
- Navigate to Settings > Integrations > API service users.
- This section is only accessible to users with admin privileges.
Create a new service user
- Click on “Create service user” or similar option.
- Provide a name and description for the service user to identify its purpose.
- Assign the required permissions based on your integration needs.
- Permissions needed, see Permissions section
- Save the service user and copy both the Service User ID and Service User Token immediately, as you might not be able to view the token again.

Permissions

What You Need to Provide Us

After creating the service user, you need to share the following credentials with us for integration:

Required Credentials:

Service User ID - The unique identifier for your service user
Service User Token (also called Service User Secret) - The authentication token

Copy both credentials from the HiBob interface after creating the service user
Share them with us through a secure channel (never include in emails or unsecured communications)
Important: You can only view the token once during creation, so make sure to copy it immediately

Using the Service User Credentials

HiBob API uses Basic Authentication. You need to combine your service user credentials and encode them properly:

Combine credentials: Join your Service User ID and Token with a colon:
```
SERVICE-USER-ID:SERVICE-USER-TOKEN
```
Base64 encode: Encode the combined string using Base64 encoding.
Set Authorization header: Include the encoded credentials in your requests:
```
Authorization: Basic <Base64-encoded-credentials>
```

Example using curl:

# First, base64 encode your credentials
echo -n "your-service-user-id:your-service-user-token" | base64

# Then use in the request
curl -X GET "https://api.hibob.com/v1/endpoint" \
  -H "Authorization: Basic <base64-encoded-credentials>"

Example with manual encoding:

curl -X GET "https://api.hibob.com/v1/endpoint" \
  -u "your-service-user-id:your-service-user-token"

Troubleshooting

If you encounter authentication issues:

Verify that your service user credentials are valid and have not expired
Ensure you’re using Basic Authentication (not Bearer) in the Authorization header
Check that your Base64 encoding is correct
Verify that your service user has the necessary permissions for the API endpoints you’re trying to access
Contact HiBob support if you continue to experience issues

Required Permissions for Employee Data Access

Based on the official HiBob documentation, service users need specific permissions to access employee data. Here’s what’s required for common use cases:

Essential Setup Steps:

Create a permission group - Service users have no permissions by default
Add the service user to the permission group
Configure three types of permissions:

Permission Types Required:

1. Features Permissions

Grant access to Bob features you need via the API
For employee data access, ensure basic API access is enabled

2. People’s Data Permissions

For basic employee listing (most common need):
- Enable “Default Employee Fields” permissions
- This includes access to: root, about, employment, and work categories
- Specifically grant: “View all employees’ [Category name] sections” for each needed category
For employee history data (work history, lifecycle changes):
- Additionally grant: “View all employees’ [Category name] section histories”
For updating employee data:
- Grant: “Edit all employees’ [Category name] sections”

3. Access Rights

Default: Access to all active/employed staff
Custom: Can be configured to specific employees or conditions
Note: By default, only active employees are accessible. To access inactive employees, you need to modify the “Lifecycle status” condition

Minimum Permissions for Employee Listing:

To provide us with employee data, your service user needs:

Features: Basic API access
People’s Data: “Default Employee Fields” with “View” permissions for root, about, employment, and work categories
Access Rights: “All employees” or “Lifecycle status equals Any” (depending on whether you want active-only or all employees)

This configuration allows the service user to access the People search API and retrieve basic employee information including names, employment details, and work information.

HiBob API