Categories and permissions
Understand how to set service user permissions to fields and categories
In Bob, employee fields are systematically organized within categories. These categories serve as the primary unit for assigning permissions, meaning that permissions are always assigned to categories rather than individual fields.
Each category is identified by a unique category ID, which varies between out-of-the-box categories and user-defined categories:
- Out-of-the-box category IDs: these IDs may appear as strings, such as 'work.' Renaming the category does not change its ID.
- User-defined category IDs: these IDs follow a specific format, such as category_1720508362305.
Field IDs and Categories
Field IDs may look like they include the category (e.g., "/work/department"), but you should not rely on this format. If you move a field to another category the ID doesn't change. Always check the field’s category using the metadata instead of looking at the field's ID. To learn more about setting permissions for fields that have been moved to a different category, see Moving fields between categories.
Find the category ID in Bob's UI
When viewing a specific category in Bob's UI, you can see the category ID as part of the URL of the page, for example:
- The out-of-the-box category would look something like this:
app.hibob.com/employee-profile/3332883884017714448#financial - The custom category would look something like this:
app.hibob.com/employee-profile/3332883884017714448#category_1720508362305
Setting permissions to categories
The Public API permissions are enabled with the same logic as the permission you enable for other users on the platform and are based on field categories. Only categories that the service user can access are included in the response.
This means that when you enable permissions to the Service User, you enable the permission to the category and, as a result, to all the fields that reside in that category.
Note: Although a Bob Admin can move fields between categories, for some fields this may affect platform behavior and other features in Bob, so before doing so it is best to ensure where else you're using the specific field across the platform. To learn more, see Set up People's data fields ↗.
Setting permissions
To learn how to set up a service user with permissions, see API Service Users.
Example:
If the service user doesn’t have permission to access the Work category, the data returned will not include fields placed under the work category.
To allow the service user to access work data or other categories, you should add to the service user’s permission group the relevant permissions:
Good to know!
Explore the Permission groups (FAQs, use cases, and more) ↗ in the The HiBob Community (for Bob admins) where you can find answers to questions like:
Finding the right permission
When setting permissions, the category name in the UI may be different from the category ID, for example if you rename the category. For example, if the 'address' category was renamed to 'Address with Custom' in the UI, when setting permissions, you should look for 'Address with Custom'.
Moving fields between categories
Bob Admins can move fields to different categories. When this happens, the field will not be accessible unless you have granted access to the new category. If you can't retrieve an employee's field through the API, please check that it is still located in the category you're trying to access.
Note that if you use the "default" read without specifying specific fields, the quickest solution is to move the field back to its original location.
Otherwise, you may need to perform a different query type, specifying the field ID you're trying to access, such as "/root/id." Please note that the field ID does not change when moving between categories—you can always find the field ID using the fields metadata endpoint. To learn more, see Call search API.
Setting permissions for sensitive user data
Fields that are considered sensitive data, such as an employee’s year of birth, require an extra layer of security. This means that you may not be able to see these fields with the permissions given to the service user.
Year of birth
To access the users' complete date of birth, including the year, you must ensure that the service user has both View and Edit permissions in the People’s Data > People > Personal permissions category.
SSN
To access the users' SSN, you must ensure the service user has both View and Edit permissions in the People’s Data > People > Identification permissions category.
To learn more about service user permissions, see API Service Users.
To learn more about the different employee fields in Bob, see People's data fields glossary ↗.
Updated 9 days ago