Good licensing UX is invisible when things work and helpful when they don’t. These patterns ensure your customers have a smooth experience.
First-run experience
The first time a user launches your app, they need to enter a license key. Make this frictionless:
Desktop apps
Show a clean, focused dialog. Don’t overwhelm with options; just a single input field and an activate button.
Welcome to YourApp
Enter your license key to get started
XXXX-XXXX-XXXX-XXXX
PurchaseActivate
- Auto-format the input as the user types (add dashes automatically).
- Accept keys with or without dashes.
- Show a “Purchase” link for users who don’t have a key yet.
- Trim whitespace; users often copy keys with trailing spaces.
Support multiple input methods to minimize friction:
# Via flag
yourapp --license-key XXXX-XXXX-XXXX-XXXX
# Via environment variable
export AUTHFORGE_LICENSE_KEY=XXXX-XXXX-XXXX-XXXX
yourapp
# Interactive prompt (if no key found)
yourapp
> No license key found. Enter your key: _
Storing the key locally
After successful validation, save the key locally so users don’t re-enter it on every launch.
import json
import os
CONFIG_DIR = os.path.join(os.path.expanduser("~"), ".yourapp")
CONFIG_FILE = os.path.join(CONFIG_DIR, "config.json")
def save_license_key(key):
os.makedirs(CONFIG_DIR, exist_ok=True)
config = load_config()
config["licenseKey"] = key
with open(CONFIG_FILE, "w") as f:
json.dump(config, f)
def load_license_key():
config = load_config()
return config.get("licenseKey")
stored_key = load_license_key()
if stored_key and client.login(stored_key):
# Authenticated silently; go straight to the app
run_app()
else:
# Show the license key dialog
key = show_license_dialog()
if client.login(key):
save_license_key(key)
run_app()
Settings page
Provide a settings or “About” page where users can see their license status:
| Field | Value |
|---|
| License key | A3K9-****-****-QHDT (partially masked) |
| Status | Active |
| Plan | Pro |
| Expires | December 31, 2026 |
| Devices | 1 of 2 slots used |
| [Deactivate] |
- Mask the license key (show first and last groups only).
- Show the expiry date prominently.
- Include a “Deactivate” button that clears the stored key and returns to the license dialog.
- If using license variables, show the plan tier.
Expiration and renewal
When a license is approaching expiration, show gentle reminders:
from datetime import datetime, timedelta
if client.login(license_key):
expires_at = client.license_variables.get("expiresAt")
if expires_at:
expiry = datetime.fromisoformat(expires_at)
days_left = (expiry - datetime.now()).days
if days_left <= 7:
show_banner(
f"Your license expires in {days_left} days. "
"Renew now to avoid interruption.",
action_url="https://yoursite.com/renew"
)
Your license has expired
Your license expired on December 31, 2026.
Renew to continue using YourApp.
Enter New KeyRenew
Trial mode
Use the Developer API to issue time-limited trial licenses:
// Create a 14-day trial license
const trial = await fetch("https://api.authforge.cc/v1/licenses", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AUTHFORGE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
appId: process.env.AUTHFORGE_APP_ID,
quantity: 1,
expiresAt: new Date(Date.now() + 14 * 86400000).toISOString(),
label: "trial",
}),
});
if is_trial:
days_left = calculate_days_remaining()
show_persistent_banner(f"Trial: {days_left} days remaining. Upgrade to keep using YourApp.")
Upgrade prompts
When a user on a lower tier tries to use a gated feature, show a helpful prompt instead of silently failing:
def export_project():
features = client.license_variables.get("features", "")
if "export" not in features:
show_upgrade_dialog(
title="Export requires Pro",
message="Upgrade to the Pro plan to unlock project export.",
action_url="https://yoursite.com/pricing"
)
return
# ... actual export logic
Graceful degradation
If your app has a free tier or limited mode, fall back to it instead of killing the app entirely:
if client.login(license_key):
run_full_app()
elif has_free_tier:
show_notice("Running in free mode. Some features are limited.")
run_limited_app()
else:
show_error("Invalid license key.")
exit(1)
Error messages
Always show user-friendly messages. Map internal error codes to helpful text:
| Error | User sees |
|---|
invalid_key | ”Invalid license key. Please check and try again.” |
expired | ”Your license has expired. [Renew now]“ |
revoked | ”This license has been deactivated. Contact support.” |
hwid_mismatch | ”This license is in use on another device. Contact support to transfer.” |
no_credits | ”Service temporarily unavailable. Please try again in a few minutes.” |
| Network error | ”Couldn’t connect to the license server. Check your internet connection.” |
no_credits or invalid_app to end users.
Offline first launch
The initial authentication always requires a network connection. Make this clear:
Connection Required
YourApp needs an internet connection for first-time activation. After that, it works offline.
Retry
ttlSeconds). 
