Skip to main content

​
Requirements

  • Python 3.9 or later
  • No external dependencies (uses only the standard library)

​
Installation

Download authforge.py and place it in your project directory:
Download authforge.py and copy it into your project.

​
Quick start

from authforge import AuthForgeClient

client = AuthForgeClient(
    app_id="YOUR_APP_ID",
    app_secret="YOUR_APP_SECRET",
    heartbeat_mode="SERVER",
)

license_key = input("Enter license key: ")

if client.login(license_key):
    print("Authenticated!")
    # Your app logic here — heartbeats run in the background
else:
    print("Invalid license key.")
    exit(1)

​
Constructor parameters

client = AuthForgeClient(
    app_id="...",               # Required — from dashboard
    app_secret="...",           # Required — from dashboard
    heartbeat_mode="SERVER",    # Required — "SERVER" or "LOCAL"
    heartbeat_interval=900,     # Optional — seconds (default: 900 = 15 min)
    api_base_url="https://auth.authforge.cc",  # Optional
    on_failure=None,            # Optional — callback(reason, exception)
    request_timeout=15,         # Optional — HTTP timeout in seconds
)

​
Login

success = client.login(license_key)
Returns True if authentication succeeded, False otherwise. On success, the SDK starts a background heartbeat thread automatically.

​
Failure callback

If authentication or a heartbeat fails, the SDK calls your on_failure callback. If no callback is set (or the callback raises an exception), the SDK calls os._exit(1). 
def handle_failure(reason: str, exception: Exception | None):
    if reason == "login_failed":
        print("Login failed — check your license key.")
    elif reason == "heartbeat_failed":
        print("Heartbeat failed — saving state and shutting down.")
        save_application_state()
    # The SDK will exit after this callback returns if you don't handle it

client = AuthForgeClient(
    app_id="YOUR_APP_ID",
    app_secret="YOUR_APP_SECRET",
    heartbeat_mode="SERVER",
    on_failure=handle_failure,
)
If you don’t set on_failure, the SDK terminates the process immediately on any failure. Always set a callback in production to handle graceful shutdown.

​
Reading variables

After a successful login, app variables and license variables are available on the client: 
if client.login(license_key):
    # App-wide variables (set in dashboard or API)
    app_vars = client.app_variables
    if app_vars.get("maintenanceMode"):
        print("Server is under maintenance.")
        exit(0)

    # Per-license variables
    plan = client.license_variables.get("plan", "basic")
    if plan == "pro":
        enable_pro_features()

​
Heartbeat modes

# SERVER mode — checks with the API every interval
client = AuthForgeClient(
    app_id="...",
    app_secret="...",
    heartbeat_mode="SERVER",
    heartbeat_interval=900,  # 15 minutes
)

# LOCAL mode — verifies locally, re-validates when prepaid block expires
client = AuthForgeClient(
    app_id="...",
    app_secret="...",
    heartbeat_mode="LOCAL",
    heartbeat_interval=900,
)
See Heartbeat Modes for a detailed comparison.

​
Full example

import signal
import sys
from authforge import AuthForgeClient

def on_auth_failure(reason, exception):
    print(f"Auth failure: {reason}")
    if exception:
        print(f"  Detail: {exception}")
    save_state()
    sys.exit(1)

def save_state():
    print("Saving application state...")
    # Your save logic here

client = AuthForgeClient(
    app_id="YOUR_APP_ID",
    app_secret="YOUR_APP_SECRET",
    heartbeat_mode="SERVER",
    heartbeat_interval=900,
    on_failure=on_auth_failure,
)

license_key = input("Enter license key: ")
if not client.login(license_key):
    print("Invalid license key.")
    sys.exit(1)

print("Licensed and running!")

# Check variables
min_version = client.app_variables.get("minVersion")
if min_version and __version__ < min_version:
    print(f"Please update to version {min_version} or later.")
    sys.exit(1)

# Your application main loop
try:
    while True:
        # App logic here
        pass
except KeyboardInterrupt:
    save_state()

​
GitHub

Full source, changelog, and issues: AuthForgeCC/authforge-python