API Reference

Init

The very first call your app makes. Init verifies your credentials, runs security checks, and hands back a session_id that every other endpoint requires.

Endpoint

POST /api/v2/init https://authly.cc
Always call this first
Init must succeed before calling any other endpoint. The session_id it returns is required by login, register, variables, and every other route. If Init fails, stop — there is nothing to proceed with.

Parameters

Field Description
owner_id Required Your developer ID from the dashboard. Identifies which account owns the app.
app_name Required Your app's name exactly as registered. Case-sensitive.
secret Required Your app's secret key. Keep private — never log or expose it in source code.
version Required Client version string, e.g. 1.0 or 1.3.2. Used for version control enforcement.
hash Optional SHA-256 hash of your compiled executable. Required only if hash checking is enabled in the dashboard.

Example Request

{
  "owner_id": "12345678",
  "app_name": "MyApp",
  "version": "1.3",
  "secret": "your-secret-key",
  "hash": "a3f2c1..."
}

Responses

Session created. Use the returned session_id in all subsequent calls. If version control is active and triggered a reminder or grace period, an update object is included — Init still passes.

{
  "success": true,
  "message": "Init success",
  "session_id": "a3f5c9d2e1b4...",
  "owner_id": "12345678",
  "app_name": "MyApp",
  "version": "1.3"
}
{
  "success": true,
  "message": "Init success",
  "session_id": "a3f5c9d2e1b4...",
  "owner_id": "12345678",
  "app_name": "MyApp",
  "version": "1.2",
  "update": {
    "available": true,
    "latest_version": "1.3",
    "download_url": "https://example.com/download",
    "auto_update_enabled": true,
    "force_update": false,
    "show_reminder": true,
    "reminder_message": "A new version is available",
    "allowed_until": null
  }
}
{
  "success": true,
  "message": "Init success",
  "session_id": "a3f5c9d2e1b4...",
  "owner_id": "12345678",
  "app_name": "MyApp",
  "version": "1.1",
  "update": {
    "available": true,
    "latest_version": "1.3",
    "download_url": "https://example.com/download",
    "auto_update_enabled": true,
    "force_update": false,
    "show_reminder": true,
    "reminder_message": "Please update before the deadline",
    "allowed_until": "2026-07-01T00:00:00Z"
  }
}

A required field is missing, or hash was omitted when hash checking is enabled.

{
  "success": false,
  "code": "MISSING_FIELDS",
  "message": "Required fields are missing"
}
{
  "success": false,
  "code": "HASH_REQUIRED",
  "message": "Hash is required for this application"
}

The secret is wrong, or the hash doesn't match any approved hash for this app.

{
  "success": false,
  "code": "INVALID_SECRET",
  "message": "Invalid secret key"
}
{
  "success": false,
  "code": "INVALID_HASH",
  "message": "Hash does not match"
}

Access denied by a security policy — app disabled, IP blocked, not whitelisted, VPN, or country block.

{
  "success": false,
  "code": "APP_DISABLED",
  "message": "This application is currently disabled"
}
{
  "success": false,
  "code": "IP_BLOCKED",
  "message": "Access denied from this IP address"
}
{
  "success": false,
  "code": "IP_NOT_WHITELISTED",
  "message": "IP address is not whitelisted"
}
{
  "success": false,
  "code": "VPN_BLOCKED",
  "message": "VPN/proxy connections are not allowed"
}
{
  "success": false,
  "code": "COUNTRY_BLOCKED",
  "message": "Access denied from this location"
}

The owner or app could not be found. Double-check owner_id and app_name.

{
  "success": false,
  "code": "OWNER_NOT_FOUND",
  "message": "Owner not found"
}
{
  "success": false,
  "code": "APP_NOT_FOUND",
  "message": "Application not found"
}

Client version is outdated or unsupported. Response always includes server_version and client_version. If auto-update is enabled, an update object with a download URL is included.

{
  "success": false,
  "code": "UPDATE_REQUIRED",
  "message": "Please update your app to the latest version",
  "server_version": "1.3",
  "client_version": "1.1",
  "auto_update_enabled": false,
  "auto_update_download_url": null
}
{
  "success": false,
  "code": "UPDATE_REQUIRED",
  "message": "Please update your app to the latest version",
  "server_version": "1.3",
  "client_version": "1.1",
  "auto_update_enabled": true,
  "auto_update_download_url": "https://example.com/download",
  "update": {
    "available": true,
    "latest_version": "1.3",
    "download_url": "https://example.com/download",
    "force_update": true,
    "auto_update_enabled": true
  }
}
{
  "success": false,
  "code": "VERSION_MISMATCH",
  "message": "This app version is not supported by the developer",
  "server_version": "1.3",
  "client_version": "2.0",
  "auto_update_enabled": false,
  "auto_update_download_url": null
}

Unexpected server error. Try again — if it persists, reach out on Discord.

{
  "success": false,
  "code": "INTERNAL",
  "message": "Internal server error"
}

How Init Works

Every request runs this exact sequence top to bottom. The first failure returns an error immediately — nothing after it runs.

START Receive Request Fields: owner_id, app_name, secret, version, hash 400 MISSING_FIELDS Look Up Owner ID Query database for the owner account 404 OWNER_NOT_FOUND Look Up App Name Find the app under this owner account 404 APP_NOT_FOUND Check App Is Enabled App must be active — not disabled from dashboard 403 APP_DISABLED Check IP Blacklist Is the caller's IP on the blacklist? 403 IP_BLOCKED Check IP Whitelist if a whitelist is configured 403 NOT_WHITELISTED VPN Detection if VPN blocking is enabled (Plus+) 403 VPN_BLOCKED Country Block Check if country blocking is enabled (Plus+) 403 COUNTRY_BLOCKED Check Hash Field Provided if hash checking is enabled in dashboard 400 HASH_REQUIRED Validate Hash Match against approved hashes in dashboard 401 INVALID_HASH Validate Secret Compare secret against your dashboard value 401 INVALID_SECRET Version Control Check if version control is configured 426 UPDATE_REQUIRED 426 VERSION_MISMATCH Remind / Grace Mode passes — but adds update{} to the response Create Session Generate Session ID, store with 24-hour expiry Build Response Include Session ID, Owner ID, App Name, version Session Created 200 OK — ready for login, register, and more Always runs Conditional step

The Session ID

A temporary access token for your session
On success, the server creates a session tied to your app and returns a hex string as session_id. Pass it to every subsequent call — login, register, variables, validate-session, and so on. Sessions expire after 24 hours and are refreshed automatically on login. If any other endpoint returns SESSION_EXPIRED or INVALID_SESSION, call Init again.
24-Hour Lifetime

Sessions are valid for 24 hours from creation. A successful login automatically extends the expiry.

One Session Per Init

Each Init call creates a new session. Old expired sessions are cleaned up automatically — no limit per app.

Version Control Modes

When version control is configured, the server compares your version against the dashboard version and any whitelist rules. Three outcomes exist for older versions:

Allow
Version whitelisted
Old version is explicitly allowed through. Init succeeds with no update object. User keeps using the old version.
Remind
Update reminder
Init succeeds (200) but includes an update object with show_reminder: true. Show a non-blocking prompt — user can still proceed.
Grace
Access until deadline
Init succeeds (200) and includes allowed_until — a deadline timestamp. After that date, the version is blocked.
When no whitelist rule matches
Client version lower than server with no whitelist entry → 426 UPDATE_REQUIRED. Client version higher than server with no whitelist entry → 426 VERSION_MISMATCH. Both responses include server_version, client_version, and an update object if auto-update is enabled.