REST API Reference
The Atslegas REST API allows programmatic interaction with the key management system. All API endpoints are prefixed with /api and communicate using standard JSON formats.
Authentication and Sessions
The API uses server-side filesystem sessions for security. Most endpoints require an active session.
Authentication Flow
- Login: Send a
POSTrequest to/api/loginwith credentials. - Session Cookie: Upon successful login, the server sets a session cookie.
- Authorization: Include this cookie in subsequent requests.
- Timeout: Sessions expire after the duration defined in
config.json(default: 3600 seconds).
Login Endpoint
POST /api/login
Request Body
{
"username": "example_user",
"password": "your_password"
}
Response (Success)
{
"success": true,
"user_id": 1,
"role": "admin"
}
User Management
Manage system users and their roles (root, admin, user).
List All Users
GET /api/user/list
Response Returns an array of user objects containing metadata.
[
{
"user_id": 1,
"username": "root",
"role": "admin",
"enabled": 1
}
]
Key Groups
Key Groups are used to categorize keys (e.g., "Old Wing," "Science Lab") and manage access permissions.
List Key Groups
GET /api/keyGroup/list
Response
[
{
"key_group_id": "1",
"name": "Main Building",
"keys": "[\"k-101\", \"k-102\"]",
"users": "[]"
}
]
Add Key Group
POST /api/keyGroup/add
Request Body
{
"name": "Science Wing",
"users": [],
"keys": ["k-201", "k-202"],
"persons": []
}
Response
{
"success": true
}
Keys and States
Manage the physical keys and their current availability status.
List All Keys
GET /api/key/list
Response
[
{
"id": "k-101",
"keyNumber": 101,
"label": "Room 101",
"category": "Standard",
"floor": 1
}
]
Get Key States
GET /api/keyState/list
This endpoint provides the real-time status (available, issued, reserved) of all keys in the system.
System Logs
The system maintains an audit trail of all key movements (issued/returned).
List Key Logs
GET /api/keyLogs/list
Query Parameters
| Parameter | Type | Description |
| :--- | :--- | :--- |
| start_time | Integer | Unix timestamp for the beginning of the range. |
| end_time | Integer | Unix timestamp for the end of the range. |
Response
{
"key_logs": [
{
"id": "log-55",
"action": "Issued",
"keyNumber": "101",
"userName": "j.berzins",
"at": "2023-10-27T10:00:00Z"
}
]
}
Error Handling
The API uses standard HTTP status codes. Errors are returned in a consistent JSON format.
| Code | Meaning |
| :--- | :--- |
| 400 | Bad Request (e.g., input exceeds length limits) |
| 401 | Unauthorized (Session expired or missing) |
| 409 | Conflict (e.g., entity already exists) |
| 500 | Internal Server Error |
Error Response Example
{
"success": false,
"error": "username too long"
}