Authentication

How client applications authenticate with Aegis, manage sessions, and handle hardware binding.

License-Based Authentication

License-based authentication is the standard flow for most applications. A client submits a license key, Aegis validates it, and returns a signed session containing user information and license details.

Authentication Flow

  1. Call /api/v1/client/init with the app_id to verify the application is reachable and retrieve its public key.
  2. Call /api/v1/client/license with the license key and an optional hardware ID hash.
  3. Aegis validates the key, checks its status and expiry, binds hardware if applicable, and returns a signed session.
  4. Send /api/v1/client/heartbeat periodically (every 5–15 minutes) to keep the session active.
  5. Call /api/v1/client/logout when the application closes to release the session.

First Activation vs. Subsequent Use

The behavior of the license endpoint differs depending on whether the key has been used before.

ScenarioBehavior
First activationLicense status changes from unused to active. A user is created automatically and the hardware ID is bound to the license.
Subsequent useAegis validates the existing hardware ID, checks the device limit, and creates a fresh session. No new user or binding is created.

Password-Based Authentication

For applications that require username and password login instead of raw license keys, Aegis supports a registration and login flow.

Registration

  1. The end user calls /api/v1/client/register with a valid license key along with a chosen username and password.
  2. Aegis activates the license and creates a user account linked to it.
  3. Future sessions are established via /api/v1/client/login using the registered username and password.

Login Flow

  1. Call /api/v1/client/login with the username, password, and optional hardware ID.
  2. Aegis validates credentials, checks the associated license, and returns a signed session.
  3. The same heartbeat and logout lifecycle applies as with license-based authentication.

Multi-Product Authentication (Game Loaders)

Single-product applications use the standard license-based or password-based flow described above — no additional steps are needed. Multi-product applications, such as game loaders that bundle several titles under one account, allow a single user to hold subscriptions to multiple products simultaneously.

Multi-Product Flow

  1. Register or log in using the standard password-based flow to establish a session.
  2. Call /api/v1/client/redeem with a product-bound license key to activate it. Each call accepts the current session_id, the key, and an optional hwid_hash.
  3. Aegis validates the key, activates the license, and creates a subscription linking the user to that product. The response includes the updated license and subscriptions list.
  4. Repeat the redeem step for each additional product key the user owns.
  5. Continue with heartbeats as normal. Every heartbeat response includes the full list of active subscriptions, so the client always knows which products are available.

Note

Products are configured in the admin dashboard under each application. Each product has a name, numeric level, and optional features JSON. License keys can be bound to a specific product at generation time. See the Products section in Features for details.

Session Management

Aegis tracks active sessions for every authenticated user. Sessions are used to enforce concurrency limits and detect anomalous behavior.

PropertyDetails
ExpirySessions expire after 24 hours of inactivity. Each heartbeat extends the expiry by another 24 hours.
Nonce rotationA new nonce is issued on every heartbeat response. The client must send the current nonce with each subsequent heartbeat to prove session continuity.
Concurrency limitThe maximum number of concurrent sessions per user is configurable per application. When the limit is reached, the oldest session is automatically evicted.

Note

Heartbeats should be sent every 5–15 minutes. If a client fails to heartbeat before the session expires, it must re-authenticate from scratch.

Hardware ID Binding

Hardware ID (HWID) binding ties a license to a specific physical machine, preventing unauthorized sharing of license keys across devices.

How It Works

  1. The client application computes a hardware fingerprint from system identifiers (CPU, motherboard, disk serial, MAC address) and sends the SHA-256 hash to Aegis.
  2. On first activation, the HWID is bound to the license. Subsequent authentication requests are validated against the stored hash.
  3. If the license allows multiple devices, new hardware IDs are accepted until the configured device limit is reached.

Multi-Device Support

Each license has a configurable device limit. When a new device authenticates with a license that has not yet reached its limit, the new hardware ID is added automatically. Once the limit is reached, authentication from unrecognized devices is rejected.

Grace Period

A configurable grace period can be set per application to delay hardware ID changes. This prevents rapid hardware swapping — for example, a user repeatedly transferring a license between machines. During the grace period, HWID reset requests are denied.

Anomaly Detection

When a hardware ID mismatch is detected — an authentication attempt from a device not bound to the license — Aegis flags the event for anomaly detection. These events are visible in the application logs and can be used to identify potential license abuse.

Note

Hardware ID binding is optional. If no HWID is sent during authentication, the license operates without device restrictions. Applications that do not require hardware locking can omit this field entirely.