API Reference

Client SDK endpoint reference for integrating with the Aegis platform.

Overview

All client-facing endpoints are served under a single base path on the Aegis instance. Every request uses POST with a JSON body, and every response follows a standard envelope.

Property	Value
Base URL	`https://aegis.dog/api/v1/client`
Method	POST with JSON body
Content-Type	`application/json`
Rate Limiting	Rate-limited endpoints return `429` with a `Retry-After` header

Response Envelope

Every response includes an Ed25519 signature that the SDK can verify against the application's public key. This prevents response tampering between server and client.

{
  "success": true,
  "payload": { ... },
  "signature": "base64-encoded Ed25519 signature"
}

Common Response Objects

Several endpoints return license and subscription objects. Their shapes are documented here and referenced throughout the endpoint sections below.

License Object

Represents an activated license key. Returned by /license, /register, and /redeem.

Field	Type	Description
status	string	License status (e.g. active, expired, banned)
expires_at	string \| null	Expiry date in ISO 8601 format, or null for lifetime licenses
product_id	string \| null	Associated product identifier, or null for single-game applications

Subscription Object

Represents an active subscription entry. Returned in the subscriptions array by /license, /login, /register, /redeem, and /heartbeat.

Field	Type	Description
id	string	Subscription identifier
product_id	string	Product this subscription grants access to
started_at	string	Subscription start date in ISO 8601 format
expires_at	string \| null	Expiry date in ISO 8601 format, or null for lifetime subscriptions

POST /init

Verifies that an application exists on the Aegis instance and returns server information along with a temporary session.

Request Body

Field	Type	Required	Description
app_id	string	Yes	Application identifier

{
  "app_id": "app_abc123"
}

Response Payload

Field	Type	Description
app_name	string	Application display name
user_count	number	Total registered users
online_count	number	Currently active sessions
session_id	string	Temporary session identifier
nonce	string	One-time value for replay prevention
server_timestamp	string	Server time in ISO 8601 format

Note

The session returned by /init is temporary. Use /license or /login to start a persistent authenticated session.

POST /license

Authenticates a client using a license key. On first use the license is activated and the hardware identifier is bound. Subsequent calls validate the key and create a new session.

Request Body

Field	Type	Required	Description
app_id	string	Yes	Application identifier
key	string	Yes	License key
hwid_hash	string	No	SHA-256 hardware identifier hash for device binding

{
  "app_id": "app_abc123",
  "key": "XXXXX-XXXXX-XXXXX-XXXXX",
  "hwid_hash": "a1b2c3d4..."
}

Response Payload

Field	Type	Description
session_id	string	Persistent session identifier
nonce	string	One-time value for replay prevention
user	object	User profile information
license	object	License details including product_id (see License Object)
subscriptions	array	Active subscription entries (see Subscription Object)

Note

First use activates the license and binds the HWID. Subsequent calls validate the existing binding and create a new session.

POST /login

Authenticates a client using a username and password. Intended for applications that use the registration flow.

Request Body

Field	Type	Required	Description
app_id	string	Yes	Application identifier
username	string	Yes	Account username
password	string	Yes	Account password
hwid_hash	string	No	SHA-256 hardware identifier hash for device binding

{
  "app_id": "app_abc123",
  "username": "user1",
  "password": "s3cret",
  "hwid_hash": "a1b2c3d4..."
}

Response Payload

Field	Type	Description
session_id	string	Persistent session identifier
nonce	string	One-time value for replay prevention
user	object	User profile information
subscriptions	array	Active subscription entries (see Subscription Object)

Note

The license field is null in the response for login-based authentication. Use /license instead if the application uses license-only authentication.

POST /register

Creates a user account tied to a license key. After registration, the client can authenticate with /login using the created credentials.

Request Body

Field	Type	Required	Description
app_id	string	Yes	Application identifier
username	string	Yes	Desired username
password	string	Yes	Desired password
email	string	No	Optional email address
key	string	Yes	Unused license key to bind to the account
hwid_hash	string	No	SHA-256 hardware identifier hash for device binding

{
  "app_id": "app_abc123",
  "username": "newuser",
  "password": "s3cret",
  "email": "user@example.com",
  "key": "XXXXX-XXXXX-XXXXX-XXXXX",
  "hwid_hash": "a1b2c3d4..."
}

Response Payload

Field	Type	Description
session_id	string	Persistent session identifier
nonce	string	One-time value for replay prevention
user	object	Created user profile
license	object	Activated license details including product_id (see License Object)
subscriptions	array	Active subscription entries (see Subscription Object)

Note

An unused license key is required. Registration activates the key and binds it to the new account. The client is automatically authenticated upon successful registration.

POST /redeem

Redeems an additional license key onto the authenticated user. Used for multi-product loaders where a single account holds multiple game subscriptions.

Request Body

Field	Type	Required	Description
session_id	string	Yes	Active session identifier
key	string	Yes	License key to redeem
hwid_hash	string	No	SHA-256 hardware identifier hash for device binding

{
  "session_id": "sess_xyz789",
  "key": "YYYYY-YYYYY-YYYYY-YYYYY",
  "hwid_hash": "a1b2c3d4..."
}

Response Payload

Field	Type	Description
license	object	Activated license details (see License Object)
subscriptions	array	All active subscriptions for the user (see Subscription Object)

Note

This endpoint requires an active authenticated session from /login or /register. Each call redeems one key. For a multi-game loader, call /redeem once per product key after authentication.

POST /heartbeat

Keeps an active session alive by extending its expiry and rotating the nonce. Should be called every 5 to 15 minutes.

Request Body

Field	Type	Required	Description
session_id	string	Yes	Active session identifier
nonce	string	Yes	Current nonce from the last response

{
  "session_id": "sess_xyz789",
  "nonce": "abc123def456"
}

Response Payload

Field	Type	Description
session_id	string	Confirmed session identifier
new_nonce	string	Rotated nonce for the next request
expires_at	string	New session expiry in ISO 8601 format
subscriptions	array	Current active subscriptions (see Subscription Object)

Note

Each heartbeat extends the session by 24 hours and rotates the nonce. The new nonce must be used for all subsequent requests. Failing to send heartbeats causes the session to expire.

POST /logout

Terminates an active session immediately.

Request Body

Field	Type	Required	Description
session_id	string	Yes	Session to terminate
app_id	string	Yes	Application identifier

{
  "session_id": "sess_xyz789",
  "app_id": "app_abc123"
}

Response Payload

Returns a confirmation message indicating the session has been terminated.

POST /file

Retrieves a distributed file by its identifier. Returns a download URL and integrity hash.

Request Body

Field	Type	Required	Description
app_id	string	Yes	Application identifier
file_id	string	Yes	File identifier
session_id	string	Conditional	Required for files marked as authenticated-only
nonce	string	Conditional	Required when session_id is provided

{
  "app_id": "app_abc123",
  "file_id": "file_001",
  "session_id": "sess_xyz789",
  "nonce": "abc123def456"
}

Response Payload

Field	Type	Description
name	string	Original file name
url	string	Temporary download URL
hash	string	SHA-256 hash for integrity verification

Note

Files configured as authenticated-only require a valid session_id and nonce. Public files can be retrieved with only app_id and file_id.

POST /variable

Retrieves a configuration variable by key. Variables are key-value pairs configured in the application dashboard.

Request Body

Field	Type	Required	Description
app_id	string	Yes	Application identifier
key	string	Yes	Variable key name
session_id	string	Conditional	Required for variables marked as authenticated-only
nonce	string	Conditional	Required when session_id is provided

{
  "app_id": "app_abc123",
  "key": "api_endpoint",
  "session_id": "sess_xyz789",
  "nonce": "abc123def456"
}

Response Payload

Field	Type	Description
key	string	Variable key name
value	string	Variable value

Note

Variables configured as authenticated-only require a valid session_id and nonce. Public variables can be retrieved with only app_id and key.

POST /log

Sends a client event to the server for remote diagnostics. Events are stored and visible in the application dashboard.

Request Body

Field	Type	Required	Description
session_id	string	Yes	Active session identifier
nonce	string	Yes	Current nonce from the last response
level	string	Yes	Event severity: `info`, `warning`, or `error`
message	string	Yes	Event message content

{
  "session_id": "sess_xyz789",
  "nonce": "abc123def456",
  "level": "error",
  "message": "Failed to load configuration from cache"
}

Response Payload

Returns a confirmation indicating the event was recorded.

Note

Accepted levels are info, warning, and error. Client logging is useful for remote diagnostics and monitoring application health without requiring direct access to end-user devices.