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

1. Login: Send a POST request to /api/login with credentials.
2. Session Cookie: Upon successful login, the server sets a session cookie.
3. Authorization: Include this cookie in subsequent requests.
4. 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"
}