Users
Retrieve users
const rql = rqlBuilder().eq('email', 'john.doe@example.com').build();
await exh.users.find({
rql,
});Using the Extra Horizon SDK or REST API's you can easily retrieve users. The permissions assigned to you determine the returned fields. You will receive either a Full User, a Patient, or a Staff view.
{
"id": "abcdef0123456789abcdef01",
"firstName": "John",
"lastName": "Doe",
"language": "EN",
"email": "john.doe@example.com",
"phoneNumber": "+32012345678",
"timeZone": "Europe/London",
"activation": true,
"roles": [...],
"staffEnlistments": [...],
"patientEnlistments": [...]
"lastFailedTimestamp": "2026-05-19T13:19:19.636Z",
"failedCount": 0,
"creationTimestamp": "2026-05-19T13:19:19.636Z",
"updateTimestamp": "2026-05-19T13:19:19.636Z"
}{
"id": "abcdef0123456789abcdef01",
"first_name": "John",
"last_name": "Doe",
"language": "EN",
"email": "john.doe@example.com",
"phoneNumber": "+32012345678",
"timeZone": "Europe/London",
"activation": true,
"patientEnlistments": [...]
}When you receive a Patient from this endpoint, the patientEnlistments property will only hold the enlistments for groups where you are a Staff member.
When you receive a Staff member from this endpoint, the staffEnlistments property will only hold the enlistments for groups where you are a Staff member.
Property overview
id
The identifier of the user.
firstName
First name of the user.
lastName
Last name of the user.
language
A supported language code see Localization service documentation.
email
Email address of the user.
phoneNumber
Phone number of the user.
activation
Boolean indicating the email address has been activated true or false.
timeZone
Time zone of the user.
roles
Array containing a description of the roles this user has obtained.
staffEnlistments
Array containing a description of the staff enlistments this user has within one or more groups.
patientEnlistments
Array containing a description of the patient enlistments this user has within one or more groups.
lastFailedTimestamp
Timestamp Information about when the last password login attempt failed.
failedCount
The number of consecutive password login attempts.
creationTimestamp
Timestamp when the user was created.
updateTimestamp
Timestamp when this user object was last updated.
Create a new user
You can use the Extra Horizon SDK to create new users from your application. This also triggers an event with the user_created type.
Check for email availability
As an application, you have the ability to check if an email is available or already in use in a user account.
Email verification
After registration, the activation attribute defaults to false. While email verification does not block using any API services, it does block the possibility to initiate a password reset. If you do not provide password reset functionality in your application, you can skip this step. For other applications, it is highly recommended to implement email verification to prevent sending emails to the wrong person.
The user service can be configured to hold a reference to an HTML template in the template service. When registration occurs, the user service will try to send an email by using this template.
The user service will provide the user's firstname, lastname, and activation_hash values to the email service. The email service adds a tracking_hash before it reaches the template service. Thus you can use these three fields in your email template. Please review the Template Service documentation to learn how to design email templates.
Resending email verification
When you make an application where email verification is a prerequisite, or when you want to provide password reset capabilities, you want your user to be able to trigger the email verification mail again.
Performing a user activation
By performing the steps mentioned higher, you can send your user an email with an activation token. Typically this is embedded inside an URL or a deep link. You can then use that token to activate the user.
Clearing user activation attempts
Users have a limited number of attempts to initiate and complete their activation. Once they reach the maximum allowed attempts, they are blocked from further attempts until their activation request is cleared. Finding and clearing an activation request can be done like this:
Change email address
When a user is logged in, he can change the email of his or another user's account, depending on the set permissions. Changing an email requires re-activating the associated account.
Password reset
Users not remembering their password is common. You want to deal with it safely in your applications. The Extra Horizon SDK provides you with the ability to do so.
Requesting a password reset email
Similar to the email verification flow, the password reset flow provides you with a reset token that you can use to set a new password for your user's account.
Resetting a password
By performing the steps mentioned higher, you can provide your user with an email containing a reset token. Typically this is embedded inside a URL or deep link towards your application. You can then use that token to reset the password of the user.
Completing a password reset will log out the target user. This action will terminate all active sessions by invalidating all authentication tokens, including OAuth1, OAuth2, and Multi-Factor Authentication (MFA) tokens for the user.
Clearing password reset attempts
Users have a limited number of attempts to initiate and complete a password reset. Once they reach the maximum allowed attempts, they are blocked from further attempts until their password reset request is cleared. Finding and clearing a password reset request can be done like this:
Password Change
When authenticated you can also implement password change functionality in your application. Changing the password requires you to resend the current password together with the new password.
Removing a user
Removing a user requires the global DELETE_USER permission. This will also trigger a UserDeleted event.
Using pin codes for email verification
The pin code mode is an alternative mode for the account activation and forgot password flows. The mode is targeted to use cases where the end user might need to manually input the secret in the application.
By default Extra Horizon uses the hash mode, this sends an email with a hash (a string of 40 hexadecimal characters) to the user. When the pin code mode is enabled and used, a pin code of 8 digits is send instead.
Setting up pin code mode
By default the pin code mode is disabled, it can be enabled with the Extra Horizon CLI User Service verification settings:
It is supported that both the hash mode and pin code mode are be used for different parts of your application, so different email templates are used to send pin codes to end users. Rather then the inputs.activation_hash or inputs.reset_hash, a inputs.pin_code field will be available to the pin code email templates. The templates can be set like this with the Extra Horizon CLI User Service email template settings:
After enabling the pin code mode and setting the email templates, pin codes can now be used in the activation and forgot password flows.
Using the pin code mode in the account activation flow
When enabled the pin code mode can be used when initiating the activation flow, during account creation, changing the email address of a user and when (re-)requesting the account activation email.
For example, the pin code mode is used by setting activationMode when creating an account:
The user receives an email showing the pin code, which the user should be able to give to your application. Then the pin code can be used to complete the activation:
Using the pin code mode in the forgot password flow
If the pin code mode is enabled for the forgot password flow, mode can be used when requesting a forgot password email:
The user receives an email showing the pin code, which the user should be able to give to your application. Then the pin code can be used to change the password:
Last updated