EasySecure.cloud - API
Introduction
This article serves as a comprehensive guide to understanding, utilizing, and integrating our API into your applications. Whether you are a seasoned developer or new to API consumption, this documentation will provide you with all the necessary information to interact effectively with our services. By leveraging this API, developers can build powerful applications, automate workflows, and integrate our capabilities into their own systems.
Our API is currently designed to provide programmatic access to the core functionality of our platform, which is focussed on user management, access control, time registration/attendance and automated reservation/credential management. Our platform is developing constantly and new functionality is added regularly. If you are still feeling something is missing, please contact us and we are happy to help you with your integration case.
We are currently supporting the following API approaches:
REST
Representational State Transfer (REST) is an architectural style for designing networked applications. It relies on a stateless, client-server communication model, where resources are identified by URLs and can be manipulated using a standard set of HTTP methods (GET, POST, PUT, DELETE, etc.). RESTful APIs are widely used due to their simplicity, scalability, and adherence to web standards.
SOAP
SOAP (Simple Object Access Protocol) is an XML-based protocol used for exchanging structured information in the implementation of web services. Unlike REST (Representational State Transfer), SOAP is a protocol-based web service approach that uses XML for message formatting and supports a wide range of features for secure, reliable, and structured communication in enterprise environments.
REST - Getting Started
To begin using our REST API, administrator user access to an active EasySecure Cloud environment is needed. Please contact your application manager if your EasySecure user account is not setup properly or create a separate login user for the API development. An email address is mandatory for authentication with the API.
If you would like access to a demo environment or you have no active subscription yet, feel free to contact us.
If you would like access to a demo environment or you have no active subscription yet, feel free to contact us.
- Step 1 – Login EasySecure
Helpcenter Article - How to login - Step 2 – Create a new administrator or check existing admin
Helpcenter Article - How to create an admin - Step 3 - Activate API access
Helpcenter Article - How to activate REST API access - Step 4 - API overview and functions – Postman
This page provides details about the API, including endpoints, request methods, parameters, headers, and example responses.
EasySecure REST API - Postman Page - Step 5 - Test API - Swagger
Swagger UI provides an interactive, web-based UI that allows users to visualize and interact with the API's resources without needing any additional software. One of the most useful features is the "Try it out" button, which lets users send real requests to the API directly from the documentation page. This helps developers understand how the API works in practice.
EasySecure REST API - Swagger Page
REST - Authentication
For authentication with the REST API we use Firebase. The registration in Firebase can be done by setting up an email address in EasySecure. The login credentials from the email invitation can be used to generate an "idToken". This token is used for most of the REST API POST/GET
calls. We divide the authentication in two "role-based" paths, based on which functions are needed for the integration or application. Functions are only available for the selected path. If for example functions from both paths are needed for the integration, two different tokens need to be used for retreiving the correct data: one for each path.
1. User (currently used for mobile app solutions)
2. Admin (widely used for integrations)
For authentication please make sure the correct POST method is used.
User
This method is used when FireBase user invite is send via the user menu. "User" can retrieve the token with a POST call to https://api.easysecure.cloud/users/login.
In case the idToken is expired, a new token can be retrieved with a POST call to https://api.easysecure.cloud/users/refreshToken
Admin
This method is used when FireBase user invite is send via the Administrator menu. "Admin" can retrieve the token with a POST call to https://api.easysecure.cloud/admins/login
In case the idToken is expired, a new token can be retrieved with a POST call
to https://api.easysecure.cloud/admins/refreshToken
For
this function a POST call must be made with the following Headers and Parameters:
Headers:
- Content-type: application/json.
- Accept: application/json.
Parameters:
- company – required parameter, string, the exact name of the Company which the user is linked to. Note that the company is case sensitive. If the company name is "EasySecure" for example, the value "Easysecure" is not accepted.
- email – required parameter, string which represents the email address of the user.
- password – required parameter,
string.
If the POST call is successful the client will receive as response status Code 200 along with the tokens which can be used for other calls. These are:
- idToken – string, valid only
for 1 hour. This must be set in the HTTP headers for API calls that require the
User to be authenticated. (format: Authorization: Bearer)
- refreshToken– string, valid indefinitely, this can be used to
retrieve a new idToken with the endpoint /users/refreshToken.
REST - Rate Limiting and Quotas
Our REST API currently has no rate limiting. We will update this information if changes are made regarding this in the future.
REST - Error Handling
In some cases the API can return calls with error responses. Most are generic and some are specific messages depending on the used function. Please check the Postman page for detailed descriptions. For overview we listed the possible messages below:
Function | Code | Message |
POST /admins/login | 404 | Invalid Login Credentials |
500 | Incorrect EasySecure setup | |
500 | It is currently not possible to create a new account/user | |
500 | Can not save data | |
500 | It is currently not possible to delete the account | |
500 | Unknown exception | |
500 | Firebase unknown exception |
POST /admins/refreshToken | 400 | Required field missing |
401 | Invalid refresh token |
POST /admins/logout | 500 | Can't revoke token from Firebase |
POST /admins/resetPasswordRequest | 500 | Passwords request email not sent |
500 | Can not save data |
POST /admins/resetPassword | 500 | Passwords request token used |
500 | It is currently not possible to change the password | |
500 | Can not save data |
POST /admins/getLogs | 400 | Incorrect filter |
POST /admins/getLogsMinMaxIds | 400 | Incorrect format |
POST /admins/setUsers | 400 | Required field missing |
400 | wsAltUserId needs to have a value. Cannot be empty | |
400 | Incorrect format |
POST /admins/sync | 404 | User not found |
404 | User not linked to location |
POST /admins/getSyncLogs | 400 | Incorrect format |
POST /admins/getUsers | 500 | Info label function not found |
POST /admins/syncUserToFirebase | 400 | Required field missing |
500 | Info label function not found | |
500 | User already registered in Firebase | |
500 | Passwords request email not sent | |
500 | Can not save data |
POST /admins/setLogs | 400 | Required field missing |
POST /admins/setWsAltUserId | 400 | Required field missing |
404 | The user id needs to be integer |
POST /users/login | 404 | Invalid Login Credentials |
500 | Incorrect EasySecure setup | |
500 | It is currently not possible to create a new account/user | |
500 | Can not save data | |
500 | It is currently not possible to delete the account | |
500 | Unknown exception | |
500 | Firebase unknown exception |
POST /users/refreshToken | 400 | Required field missing |
401 | Invalid refresh token |
POST /users/logout | 500 | Can't revoke token from Firebase |
POST /users/resetPasswordRequest | 500 | Passwords request email not sent |
500 | Can not save data |
POST /users/resetPassword | 500 | Passwords request token used |
500 | It is currently not possible to change the password | |
500 | Can not save data |
POST /users/setConsent | 400 | Required field missing |
500 | Value already set | |
500 | Can not save data |
POST /users/setLicensePlate | 400 | Required field missing |
403 | No permission | |
500 | Can not save data |
POST /users/setCardPin | 400 | Required field missing |
403 | No permission | |
500 | Can not save data |
POST /users/getPicture | 404 | Picture not found |
POST /users/setPicture | 400 | Required field missing |
403 | User did not give GDPR consent | |
403 | No permission | |
500 | No action selected | |
500 | Picture extension not supported |
POST /users/sendSupportMail | 400 | Required field missing |
400 | Invalid email | |
500 | Support request email not sent |
POST /users/changePassword | 400 | Required field missing |
500 | It is currently not possible to change the password |
REST - Examples
The majority of integrations that we currently connect with, follow a certain logical order in which they support our system functionalities. In most designs, this order will be used for core functionality. In this chapter some examples of integration types are displayed with the API calls used, to show how to build up these cases.
Default HR
/ Time registration
1. Import
Employees
The first thing to do is to make sure the employee data is available in our software. For every employee we need an unique identifier to match the correct info from the system. This can be a worker or employee id, or any unique value that can represent the employee in the HR system. This helps to always update the same employee instead of creating a new entry everytime data is changed. The so-called "wsAltUserId" parameter can be added with this value and is also visible in EasySecure for the end user.
The first thing to do is to make sure the employee data is available in our software. For every employee we need an unique identifier to match the correct info from the system. This can be a worker or employee id, or any unique value that can represent the employee in the HR system. This helps to always update the same employee instead of creating a new entry everytime data is changed. The so-called "wsAltUserId" parameter can be added with this value and is also visible in EasySecure for the end user.
POST /admins/setUsers
Before importing the users check which access groups are available in Easysecure. This helps to add the correct access rights to the user for use with the time registration terminal. This can be done by making the following call:
POST /admins/getGroups
2. Sync Users (optional)
Our time registration terminals need to be updated to add the correct user data to the hardware. The physical tags, cards or other credentials used by the employee always need to be registered in the system first. Sometimes these credentials can be added via the API, or are added during the onboarding. The correct access group is mandatory to make sure a user is updated in the hardware. A sync then can be initialized in the software, but also via the API with the following call:
Our time registration terminals need to be updated to add the correct user data to the hardware. The physical tags, cards or other credentials used by the employee always need to be registered in the system first. Sometimes these credentials can be added via the API, or are added during the onboarding. The correct access group is mandatory to make sure a user is updated in the hardware. A sync then can be initialized in the software, but also via the API with the following call:
POST /admins/sync
POST /users/sync
3. Export logs
Finally, when users where added and updated in the time terminal, logs will be generated with specific events (IN, OUT, DUTY IN, DUTY OUT etc) when the user starts the registration. These events with time and date stamps can be collected with the following call:
POST
/admins/getLogs
Default reservation and automated credential creation
1. Import reservations
Reservations from the reservation system can be added in EasySecure as users. This can be done with the following call:
POST /admins/setUsers
1. Import reservations
Reservations from the reservation system can be added in EasySecure as users. This can be done with the following call:
POST /admins/setUsers
2. Create credential
When the user is created, a mobile key or face template can be generated via the API:
Mobile Key
POST /admins/getUsers – if you need to
see/check details for a certain user
POST /admins/setUsers – to update
the user with a mobile Key
Face Template
POST /users/setPicture
3. Sync Users
After the user, credential and access group is added, the users can be synced/activated in the devices with the following call:
After the user, credential and access group is added, the users can be synced/activated in the devices with the following call:
POST /admins/sync
POST /users/sync
Default
Access Control
1. Import Users
+ Access Group(s)
The first thing to do is to make sure the employee data is available in our software. For every employee we need an unique identifier to match the correct info from the system. This can be a worker or employee id, or any unique value that can represent the employee in the HR system. This helps to always update the same employee instead of creating a new entry everytime data is changed. The so-called "wsAltUserId" parameter can be added with this value and is also visible in EasySecure for the end user.
POST
/admins/setUsers
Before importing the users, check which access groups are available in Easysecure. This helps to add the correct access rights to the users. This can be done by making the following call:
Before importing the users, check which access groups are available in Easysecure. This helps to add the correct access rights to the users. This can be done by making the following call:
POST /admins/getGroups
2. Create credential or
Import Mifare Card number
The physical tags, cards or other credentials used by the employee always need to be registered in the system first. Sometimes these credentials can be added via the API, or are added during the onboarding. This can be done with the following call:
The physical tags, cards or other credentials used by the employee always need to be registered in the system first. Sometimes these credentials can be added via the API, or are added during the onboarding. This can be done with the following call:
POST
/admins/setUsers
3. Sync Users
The correct access group is mandatory to make sure a user is updated in the hardware. A sync then can be initialized in the software, but also via the API with the following call:
POST /admins/sync
POST /users/sync
4. Export logs
To retreive the access logs, use the following call:
To retreive the access logs, use the following call:
POST /admins/getLogs
SOAP - Getting Started
To begin using our SOAP API, an active EasySecure Cloud environment is needed. To create a secure connection to the webservice, a security key will be provided by our support team. This key can only be used for the EasySecure environment specific to the customer or provided demo environment.
If you would like to retreive your security key, access to a demo environment or if you have no active subscription yet, feel free to contact us.
After you have retrieved the security key, please check our SOAP Development page for more information about this API.
If you would like to retreive your security key, access to a demo environment or if you have no active subscription yet, feel free to contact us.
After you have retrieved the security key, please check our SOAP Development page for more information about this API.
Support and Feedback
Related Articles
BioStar 2 - API & SDK Quick Start Guide
Links Our API and SDK manuals are available for public view in the links below: BioStar 2 API version 2 (for BioStar 2.4 and above) BioStar 2 Device SDK API In order to use our API, you must use BioStar 2 and configure BioStar 2 Cloud feature. ...EasySecure.cloud - Hoe kan ik inloggen?
Ga met uw browser naar de volgende webpagina en open uw EasySecure-omgeving: https://easysecure.cloud U kunt inloggen met een juiste combinatie van bedrijfsnaam, gebruikersnaam en wachtwoord. Let op! Deze gegevens zijn hoofdlettergevoelig. Wanneer u ...EasySecure.cloud - iLOQ
Overview This article summarizes all relevant information needed to setup and use the iLOQ integration. With this integration you will be able to activate/de-activate pre-programmed iLOQ S5 Keys, Key Fobs and Mobile Keys for S50 locks in EasySecure. ...EasySecure.cloud - Hoe werkt de webservice?
Wij geloven in “best of breed” oplossingen. Wat bedoelen wij daarmee? Er zijn veel uitstekende softwareoplossingen voor deelgebieden beschikbaar. Denk bijvoorbeeld aan het beste HR-pakket, het beste planningspakket etc. “Best of breed” oplossingen ...EasySecure.cloud - Hoe kan ik toestemming voor biometrie vastleggen in de software?
Bekijk onze privacy pagina voor de meest recente informatie over dit onderwerp Biometrie staat voor gemak en veiligheid. Geen verloren kaarten, vergeten codes en geen passen in omloop. Veel gemak voor werkgever én werknemer, maar bij ...