SDK Integration Best Practices

This is the most important page in the documentation. Read it before shipping your integration.

License key input UX

Desktop apps

Use a dialog or popup window on first launch. After successful validation, store the key locally (e.g., in a config file, registry, or app data directory) so users don’t re-enter it every time. Provide a “Deactivate” or “Change License” option in settings.

┌──────────────────────────────────────────┐
│..........................................│
│....Enter License Key.....................│
│..........................................│
│...┌──────────────────────────────────┐   │
│...│..XXXX-XXXX-XXXX-XXXX.............│...│
│...└──────────────────────────────────┘   │
│..........................................│
│....[ Purchase ]..........[ Activate ]....│
│..........................................│
└──────────────────────────────────────────┘

CLI tools

Support multiple input methods:

Command-line flag: --license-key XXXX-XXXX-XXXX-XXXX
Environment variable: AUTHFORGE_LICENSE_KEY
Config file: ~/.yourapp/config.json or ~/.yourapp/license
Interactive prompt: Ask on first run if no key is found

import os

key = (
    args.license_key
    or os.environ.get("AUTHFORGE_LICENSE_KEY")
    or load_from_config()
    or input("Enter license key: ")
)

Game mods and plugins

Read the key from a config file in the mod/plugin directory (e.g., plugins/your-mod/license.txt or config.yml). Don’t block the game’s main thread with a dialog — load the key at plugin initialization and fail gracefully.

Handle each error code with an appropriate user-facing message. Never expose internal details to end users.

SDK error	Cause	What to show the user
`invalid_app`	Your App ID or Secret is wrong	”Authentication failed. Please contact support.” (This is a developer error.)
`invalid_key`	The license key doesn’t exist	”Invalid license key. Please check and try again.”
`revoked`	The license was revoked	”This license has been deactivated. Contact support.”
`expired`	The license has expired	”Your license has expired. [Renew link]“
`hwid_mismatch`	All HWID slots are full	”This license is already in use on another device. Contact support to reset.”
`no_credits`	App developer ran out of credits	”Authentication service temporarily unavailable. Please try again later.”
`blocked`	HWID or IP is blacklisted	”Authentication failed. Please contact support.”
Network error	No connectivity	”Could not connect to authentication server. Check your internet connection.”

Never expose no_credits to end users — this is your billing issue, not theirs. Show a generic “temporarily unavailable” message.

Network error retry

On network failures, retry 2–3 times with exponential backoff before giving up:

import time

MAX_RETRIES = 3
for attempt in range(MAX_RETRIES):
    if client.login(license_key):
        break
    if attempt < MAX_RETRIES - 1:
        time.sleep(2 ** attempt)  # 1s, 2s, 4s
else:
    print("Could not connect to authentication server.")
    exit(1)

Heartbeat failure handling

Don’t kill the app immediately. The user could lose unsaved work. A heartbeat failure might be a momentary network blip.

The grace period pattern

When a heartbeat fails, start a countdown. Show a non-intrusive warning. If the next heartbeat succeeds, cancel the countdown.

import threading

grace_timer = None
GRACE_PERIOD = 300  # 5 minutes

def on_failure(reason, exception):
    global grace_timer
    if reason == "heartbeat_failed":
        if grace_timer is None:
            grace_timer = threading.Timer(GRACE_PERIOD, force_shutdown)
            grace_timer.start()
            show_warning("License verification failed. "
                        "The app will close in 5 minutes unless connectivity is restored.")
    elif reason == "login_failed":
        force_shutdown()

def on_heartbeat_success():
    global grace_timer
    if grace_timer:
        grace_timer.cancel()
        grace_timer = None
        hide_warning()

def force_shutdown():
    save_application_state()
    show_message("License verification failed. Your work has been saved.")
    exit(1)

Application-specific behavior

App type	On heartbeat failure
Creative tools (editors, DAWs, IDEs)	Auto-save the project. Show a dialog with a “Retry” button. Only close after N consecutive failures.
Games	Pause the game and show a modal overlay. Don’t close to desktop.
CLI / batch tools	Log the failure. Continue current operation. Exit after it completes if still failing.
Services / daemons	Log with severity. Continue running through transient failures. Only shut down after sustained failure.

Always save before terminating

def on_failure(reason, exception):
    save_application_state()  # Always save first
    log_failure(reason, exception)  # Log for debugging
    show_user_message(reason)  # Inform the user
    # Then exit after a delay or user acknowledgment

The `onFailure` callback pattern

Every SDK language follows the same pattern. Your callback receives a reason string and an optional exception:

def on_failure(reason: str, exception: Exception | None):
    save_state()

    if reason == "login_failed":
        show_error("Authentication failed.")
    elif reason == "heartbeat_failed":
        show_warning("License check failed. Retrying...")

    log(f"AuthForge failure: {reason}", exception)
    # Return normally — the SDK will exit if you don't handle it

client = AuthForgeClient(
    app_id="...",
    app_secret="...",
    heartbeat_mode="SERVER",
    on_failure=on_failure,
)

Offline and poor connectivity

When to use LOCAL heartbeat mode

LOCAL mode is designed for applications where users may not always have internet access:

The initial login() call always requires network — make this clear in your app’s system requirements.
After login, LOCAL mode verifies the stored signature locally without network calls.
When the prepaid session block expires (~25 hours), the SDK makes a new validate call to refresh.
Revocations don’t take effect until the prepaid block expires and the next validate call.

SERVER mode tolerance

Even in SERVER mode, individual heartbeat failures don’t immediately trigger shutdown (the SDK handles this internally). The failure callback fires when the SDK determines the session is truly invalid — not on every transient network blip. First launch always requires network. Document this in your app’s requirements.

Multi-instance and multi-window

If your app can be opened multiple times on the same machine:

Only one instance should authenticate. Use a lockfile or IPC mechanism to coordinate.
All instances share the same HWID, so extra instances won’t consume HWID slots.
Each login() call consumes a credit. If your app opens 10 windows, don’t call login 10 times.

import os
import sys

LOCK_FILE = "/tmp/yourapp.lock"

def acquire_lock():
    if os.path.exists(LOCK_FILE):
        return False  # Another instance is running
    with open(LOCK_FILE, "w") as f:
        f.write(str(os.getpid()))
    return True

def release_lock():
    if os.path.exists(LOCK_FILE):
        os.remove(LOCK_FILE)

if not acquire_lock():
    # Secondary instance — skip auth, connect to primary via IPC
    connect_to_primary()
else:
    # Primary instance — authenticate
    if client.login(license_key):
        run_app()
    release_lock()

Version updates

The same license keys work across all versions of your app. You don’t need to regenerate keys when pushing an update.
Use app variables to enforce a minimum version:

if client.login(license_key):
    min_version = client.app_variables.get("minVersion")
    if min_version and current_version < min_version:
        print(f"Please update to version {min_version} or later.")
        exit(1)

Anti-tampering tips

Protect your App Secret

Don’t log the app secret anywhere. Don’t store it in plain text in the binary. Use environment variables or encrypted configuration.

Authenticate early

Call login() early in your app’s startup, not lazily. Don’t let the app run unprotected code paths before authentication.

Minimize error details

Don’t expose internal auth failure details to the user. “The HMAC check failed” helps attackers — just say “Authentication failed.”

Don't trust the client

Assume the binary can be modified. Critical business logic that depends on license status should check variables, not just a boolean flag.

Use SERVER heartbeat mode for high-value software

LOCAL mode can be bypassed by freezing the system clock. SERVER mode requires a valid signed response from the API.

SDKs

​License key input UX

​Desktop apps

​CLI tools

​Game mods and plugins

​Error handling on login

​Network error retry

​Heartbeat failure handling

​The grace period pattern

​Application-specific behavior

​Always save before terminating

​The onFailure callback pattern

​Offline and poor connectivity

​When to use LOCAL heartbeat mode

​SERVER mode tolerance

​Multi-instance and multi-window

​Version updates

​Anti-tampering tips

License key input UX

Desktop apps

CLI tools

Game mods and plugins

Error handling on login

Network error retry

Heartbeat failure handling

The grace period pattern

Application-specific behavior

Always save before terminating

The `onFailure` callback pattern

Offline and poor connectivity

When to use LOCAL heartbeat mode

SERVER mode tolerance

Multi-instance and multi-window

Version updates

Anti-tampering tips