- Overview
- Creating the REST API access levels
- Creating the REST API users
- Generating the REST API keys
- Additional Information
Overview
The Humanforce REST API is available to all Humanforce Cloud customers starting in version 4.8.2 (although this version has limited endpoints available). New endpoints have been added with subsequent versions of Humanforce. Therefore, we recommend that you are on the latest version to take advantage of the full set of endpoints available. Talk to your Account Manager to upgrade and also find out how you can move to automatic upgrades.
Note: For data security and auditing, it is best practice to create separate users with the
appropriate access level permissions and link it to the API key. A new API key should be set
up for each use. Never share API keys across multiple vendors.
Creating the REST API access levels
The level of information you can access via the Humanforce API depends on the level of access that the user has in Humanforce (i.e. if the level cannot see timesheet information, you can't get timesheet information via an API call).
Your Humanforce configuration may already include a pre-configured access level called 'WS API Access'. Check if this exists first before creating a new access level.
For security purposes, we recommend not giving a level more access than it needs. This will prevent third party vendors or internal staff using the API from potentially having the ability to access information they shouldn't see. As an example, if you are using the API to provide timesheet data for a third party vendor, you likely would not want them to also have access to employees' personal details.
You will therefore need to set up new access levels for the API users, with exactly the access they need. We recommend setting up a separate access level for each API user so that you are able to precisely control what each vendor can access.
The access levels can be set up in either Humanforce Web or the Back Office, with the Back Office having the ability to copy permissions from an existing level so you do not have to start from scratch.
If using the Back Office, go to Setup > Access Levels and click Add to create your new level. Give your level a clear name, such as naming it after the party that will use it e.g. "[Vendor Name] API Access."
You can then Import Existing settings from an existing access level on the Permissions tab and then update the permissions as needed.
If using Humanforce Web, go to Admin > Access Levels, and click Add. You would still give the level a clear name, but will need to tick the necessary permissions needed instead of importing.
In addition to the permissions that decide what information can be accessed through the API, you will also need to tick the box under REST API for Allow API access.
Note: You will only be able to create API keys for users at or below your access level. As
you set up the Access Level, please confirm that the Auth Level field has been set to a
higher number or the same number as the one for your user. The auth level defines data
visibility based on organisation hierarchy, such as visibility of costs for admin employees.
Creating the REST API users
In Management > Employee Management, either create a new employee or search for an existing employee and clone the profile.
Set the new employee code and name to indicate who is using it (i.e. which vendor) and that it's an API User.
In the Employment section, put the new user on the API Access level that you created earlier. Also make sure Include in payroll export is not ticked.
Link the employee to the proper locations, departments, and roles (if not done from the cloning process). Then click Apply to create the profile.
Generating the REST API keys
Navigate to the Admin page.
In the Security Configuration section, click API Key Management.
Note: If you do not see API Key Management as an option, first check that your access level
has View API keys ticked under in the REST API permission. (You will also need the option to
Allow create/edit of API keys and Manage API keys for all users to continue with the
following steps.)
If you have these permissions selected, but still do not see API Key Management, please
create a support ticket or reach out to your account manager so that you can be issued an
updated licence.
Click Add new record.
Set the Name of the key to once again indicate the vendor or party using it. We also recommend using the Comments to provide details on what areas can be accessed with this API key. Set the Linked user to the user you just created.
Copy the API Key and Secret and put into the application that is using the API or provide to the vendor. Save when finished.
Note: Although you can come back and copy the API Key at any time, the Secret key
will be hidden after being saved. You can always Re-generate the Secret key, if needed,
which will deactivate any applications using the old secret key.
As a best practice, we recommend re-generating new secret keys regularly (every 30-90
days), much like resetting a password, to keep your data secure.
Additional Information
Additional information about the Humanforce REST API, including limits and how to find the available endpoints, can be found in the Humanforce REST API Overview