KB008: Configure HRMS Integration APIs

Article ID: KB008

Last Updated: June 21, 2025

Applies To: HySecure Gateway 7.1 and above

Category: Integration & API Features

Overview

This guide explains how to configure HySecure APIs for HRMS integration, enabling automated attendance tracking based on user login activity. The APIs provide login/logout data in JSON format with JWT-based authentication for secure access to corporate HRMS systems.

Prerequisites

HySecure Gateway 7.1 or higher
Security Officer or Administrator access to the HySecure Management Console
SSH access to the HySecure gateway active node
Understanding of JWT authentication
An HRMS system capable of consuming REST APIs
The reporting database must be enabled to generate user reports

Benefits

Automated Attendance Tracking: Eliminate manual attendance marking.
Remote Work Support: Track attendance for work-from-home scenarios.
Improved Efficiency: Streamline HR processes with automated data.
Flexible Filtering: Customize data retrieval based on various criteria.

API Terminology

Term	Description
Domain	The HySecure Domain name to which users belong.
Start Date	Beginning date for the report period.
End Date	Final date for the report period.
User Name	The specific user whose login/logout data is requested.
Start of Day	Time is considered as the start of the day for reporting (useful for shift-based environments).

Configuration Procedure

Enable Docker Service

Access Management Console
- Log in to the HySecure Management Console as a Security Officer or Administrator.
Navigate to Server Settings
- Go to Settings > Global > Server.
- Find the External API Settings section.
Configure Docker Settings
- Check the box for "Enable Docker".
- Enter the local network IP address in the Provide local network IP field.
- This IP will be assigned to the Docker service running on the Active HySecure gateway.
- Docker service will be used by HySecure APIs for HRMS.

API Usage Procedure

Step 1: Generate JWT Authentication Token

API Endpoint

POST https://<VIP>/api/v1/auth/connect

Request Format

curl -k -X POST https://172.28.1.121/api/v1/auth/connect \
  -H "Content-Type: application/json" \
  -d '{
    "username": "NCEqHaAuDcI9FMY9ZFVs",
    "password": "]XKkxfgou@{NRm)zUd=K3dzk"
  }'

Request Parameters

Parameter	Description	Required
`username`	API username (contact Accops support)	Yes
`password`	API password (contact Accops support)	Yes

Response Format

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Important Notes

Replace <VIP> with the virtual IP address of the HySecure cluster.
Contact the Accops support team for the API username and password.
Generate a new token for each API session.

Note

The generated JWT token will only be valid for the next 2 minutes.

Step 2: Fetch User Reports

API Endpoint

POST https://<VIP>/api/v1/reporting/sessions

Request Format

curl -k -X POST https://172.28.1.121/api/v1/reporting/sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{
    "Filters": {
      "EndDate": "2025-06-06",
      "StartDate": "2025-06-01",
      "UserName": "All Users",
      "StartOfDay": "00:00:00",
      "RequestDate": "2025-06-06"
    }
  }'

Request Parameters

Parameter	Description	Format	Required
`EndDate`	Final date for the report period	YYYY-MM-DD	Yes
`StartDate`	Starting date for the report period	YYYY-MM-DD	Yes
`UserName`	Specific user or "All Users"	String	Yes
`StartOfDay`	Start time for day calculation	HH:MM:SS	Yes
`RequestDate`	Date of API request	YYYY-MM-DD	Yes

Response Format

{
  "statusCode": 200,
  "statusMessage": "Data fetched successfully",
  "responseDate": "2025-02-13T10:53:56.3567571Z",
  "data": [
    {
      "UserID": "user_4",
      "Realm": "Default",
      "FirstLoginDateTime": "2025-01-01 15:30:00",
      "LastLogoutDateTime": "2025-01-01 21:10:00"
    }
  ]
}

Response Fields

Field	Description
`statusCode`	HTTP status code (200 = success)
`statusMessage`	Human-readable status message
`responseDate`	API response timestamp
`data`	Array of user session data
`UserID`	Username
`Realm`	HySecure domain/realm
`FirstLoginDateTime`	First login time for the period
`LastLogoutDateTime`	Last logout time for the period

API Integration Examples

Example 1: Daily Attendance Report

Use Case: Fetch attendance for all users for specific date:

curl -k -X POST https://172.28.1.121/api/v1/reporting/sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{
    "Filters": {
      "EndDate": "2025-02-13",
      "StartDate": "2025-02-13",
      "UserName": "All Users",
      "StartOfDay": "08:00:00",
      "RequestDate": "2025-02-13"
    }
  }'

Example 2: Weekly Report for Specific User

Use Case: Get weekly attendance data for individual user:

curl -k -X POST https://172.28.1.121/api/v1/reporting/sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{
    "Filters": {
      "EndDate": "2025-02-13",
      "StartDate": "2025-02-07",
      "UserName": "john.doe",
      "StartOfDay": "09:00:00",
      "RequestDate": "2025-02-13"
    }
  }'

Example 3: Shift-Based Reporting

Use Case: Report for night shift workers with different start time:

curl -k -X POST https://172.28.1.121/api/v1/reporting/sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -d '{
    "Filters": {
      "EndDate": "2025-02-13",
      "StartDate": "2025-02-13",
      "UserName": "All Users",
      "StartOfDay": "22:00:00",
      "RequestDate": "2025-02-13"
    }
  }'

Troubleshooting

Common Issues:

Authentication Failures:

Issue: Invalid username/password.
Solution: Verify credentials with Accops support.
Check: Ensure the correct API endpoint URL.

Token Expiration:

Issue: JWT token expired (>2 minutes).
Solution: Generate a new token before each API call.
Prevention: Implement automatic token refresh.

No Data Returned:

Issue: Empty data array in response.
Check: Verify date range and user filters.
Verify: Confirm users logged in during the specified period.
Validate: Check whether the logging is enabled (Step 1).

Docker Service Issues:

Issue: API endpoints are not responding.
Check: Verify Docker service is running.
Solution: Restart the Docker service if needed.
Contact: Accops support for Docker configuration issues.

Network Connectivity:

Issue: Cannot reach API endpoints.
Check: Network connectivity to the HySecure gateway.
Verify: Firewall rules allow API traffic.
Test: Use curl or ping to verify connectivity.