A user account gives an employee in Humanforce HR access to the Humanforce HR platform (i.e. allows them to sign in and view their dashboard, and conduct business as usual activities). A person can exist in Humanforce HR without a user account being assigned to them, however they won’t be able to sign into the platform.
User accounts can be created and managed via Humanforce HR's public API.
This article covers:
- What is a User Account in Humanforce HR?
- Creating a User
- User Synchronisation
- Updating a User
- Key Considerations
- FAQs
What is a User Account in Humanforce HR?
A user account gives an employee in Humanforce HR access to the Humanforce HR platform (i.e. allows them to sign in and view their dashboard, and conduct business as usual activities). A person can exist in Humanforce HR without a user account being assigned to them; however they won’t be able to sign into the platform.
User accounts also provide the basis for permissions management in Humanforce HR. Permission Groups allow system administrators to delegate different levels of access in Humanforce HR to users. A user account usually has a permission groups assigned to them and can be managed by the Humanforce HR API.
User management refers to the process of creating and updating user accounts within Humanforce HR. This can be done using our public API to allow for programmatic access to the user management functionality.
User management via the API involves making HTTP requests to the users endpoint. Using users endpoint, you can Create, Find and Update user accounts in Humanforce HR.
Creating a User
The "create a user" endpoint is an API endpoint that allows a client application to create a new user account within Humanforce HR. This endpoint is used to register new users and implemented as an HTTP POST request.
The person object included in this request identifies which person in Humanforce HR, the user account should be assigned to. While you can include all of the filtering fields in this example, this is not mandatory. It is recommended that you use one unique identified (ID or primaryEmailAddress).
The permissionGroups object asserts what permissions the user account should be created with. You can adjust different permission groups in your tenant Permission settings. The permissionGroups ID, can be found in the URL of the relevant permission group.
Settings > Permissions > Edit
Alternatively, you can List All Permission Groups by making a HTTP GET request to the /permission-groups endpoint.
To create a user account, perform a POST request.
"url": https://api.intellihr.io/v1/users"method": 'POST'"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": tenantname
}{
"isEnabled": true,
"username": "BruceWayne",
"person": { "id": "8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9",
"name": "Bruce Wayne",
"primaryEmailAddress": "bruce.wayne@example.com",
"employeeNumber": "00001",
"autoIncrementIntellihrId": "1000"
},
"permissionGroups": [
"fd652f39-db15-4a12-8c71-a48358ee9709"
]
}User Synchronisation
Many of our customers need to keep their user accounts synchronised between Humanforce HR and their other systems (i.e. Active Directory, Identity Management Provider). Synchronising Humanforce HR with your AD / IdP can help streamline the process of granting employees access to the resources they need to do their jobs. Keeping your users accounts in sync ensures that your employees have appropriate level of access to the resources they need.
Accessing Active Users
In order to keep user accounts in sync with Humanforce HR, you first need to know which users are active. There are two ways you can access active users via the Humanforce HR API.
List All Users
The "list all users" endpoint allows a client application to retrieve a list of all user accounts within Humanforce HR. This endpoint is typically used to retrieve a complete list of all users, along with their associated information.
To use the "list all users" endpoint, the client application would make an HTTP GET request to the endpoint URL.
"url": https://api.intellihr.io/v1/users"method": 'GET'"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": tenantname
}Keep in mind, like all list all endpoints we support, you'll need to account for pagination.
Updating a User
The "PATCH a User by ID" endpoint allows a client application to update an existing user account within Humanforce HR. This endpoint is typically used to enable or disable existing user accounts.
"url": https://api.intellihr.io/v1/users/{id}"method": 'PATCH'"headers": {
"Content-Type": 'application/json',
"Accept": 'application/json',
"Authorization": `Bearer ${apikey}`,
"Tenant": tenantname
}
{
"isEnabled": true,
"username": "BruceWayne"
}Key Considerations
Timing
Creating a user account via the API will provide that user access to Humanforce HR so you may want to consider when to automate this activity. Some businesses will want users to login and use Humanforce HR before their first day of employment, others may wait until a work email is provisioned, others may wait until the user’s first day of employment.
Where an Active Directory handles centralised identity management, this system will usually dictate when a user is created in Humanforce HR. Keep in mind that when the POST to create a user account is performed, the new user will receive a welcome email.
Standardisation
The username field is the human-friendly username a person will use to access Humanforce HR - you may want to consider a standardised approach, for example, firstname.lastname or the user’s work email address or some other value that employee will recognise and be expecting to use.
Single Sign On
If you’re building from an Identity Management platform (or similar active-directory service) to Humanforce HR and intend to have users log in via single sign-on, it’s important to consider which field will be used to match users to your Active Directory / IdM.
When someone attempts to log into Humanforce HR from a SAML authentication flow, we check the incoming claim attribute NameID and create a session for a matching user account with the following rules. If a match cannot be found the next rule will be evaluated:
If there is an Humanforce HR user account with an SSO ID configured that matches the incoming NameID
If there is an Humanforce HR user account with a Primary Email Address that matches the incoming NameID
If there is an Humanforce HR user account with the Username that matches the incoming NameID
If there is an Humanforce HR user account with the Employee Number that matches the incoming NameID
If we cannot find a match for any of these four values, we throw an error for the user.
Once an SSO configuration is enabled, the login page will change, allowing users to get redirected back to your identity provider (SP-initiated sign-on) rather than providing the normal username/password login form.
💡 Humanforce HR doesn’t currently allow SSO ID to set via the API as this is the
‘fallback’ field for SSO matching and must be asserted by a system administrator
from within Humanforce HR.It’s important to review your set up to ensure that your automation is asserting the right value for your chosen field above to allow users to be matched for authentication.
Security
Because permissions within Humanforce HR dictate who and what a user can see, it’s important to carefully review automated permission assignment.
As a general rule, we suggest only automatically assigning the default staff member permission group where possible and encouraging system administrators to log in to Humanforce HR to provide elevated permissions manually. This ensures a clear audit trail of who is provisioning elevated permissions and at what time.
Permission checking in platform is performed just-in-time, so if you do need to update a user's permissions in a hurry, this will be reflected in the platform the next time they perform an action in Humanforce HR.
FAQ's
？Why aren’t all the permissions I see in Humanforce HR available via the API ?Some permissions, like system administrator, are not available via the API as they provide complete system access.
？Why can user accounts be enabled and disabled, but not deleted ?Enabling and disabling user accounts alters access for the user but retains the historical data for the employee. This also allows users to be reactivated later if they rejoin the business.
Users can be manually deleted via the Humanforce HR platform by an administrator if necessary.
？What’s the use-case for creating a disabled user account ?Sometimes you’ll want to create a user account and populate it with a work email before you’re ready for the user to log in - this can be useful when users should only be provided access on their first day of employment, or when a user may be provided access to Humanforce HR after some other system action has been completed.