Managing Credits - AuthForge

AuthForge uses a credit-based billing model. Understanding how credits are consumed helps you estimate costs and avoid running out.

Credit consumption

Operation	Cost
Successful license validation (`POST /auth/validate`)	1 credit
Every 10 successful heartbeats (online check-ins)	1 credit
Minting an offline license file (`.authforge`)	1 credit

Failed validations (invalid key, expired, revoked) do not consume credits. Only successful authentications are billed. Heartbeats happen only if you enable online check-ins; credits are debited on every 10th successful call. The default grace-period behavior makes no heartbeat calls at all. Offline license files are billed once, at mint time, to the operator’s account (through the same debit path as validate, so your app’s burn caps apply). Verifying a file on the air-gapped machine costs nothing, and rejected mints are free. An air-gapped fleet that re-issues 90-day files costs roughly 4 credits per machine per year.

Estimating monthly usage

Formula

monthly_credits = validate_credits + heartbeat_credits

validate_credits  = active_licenses × avg_logins_per_day × 30
heartbeat_credits = active_licenses × avg_hours_per_day × (60 / heartbeat_interval_min) × 30 / 10
                    (only if online check-ins are enabled; otherwise 0)

Example calculation

Suppose you have:

500 active licenses
Users log in once per day on average
Users run the app 8 hours per day
Online check-ins enabled at the default 15-minute interval

validate_credits    = 500 × 1 × 30              = 15,000
heartbeat_credits   = 500 × 8 × 4 × 30 / 10    = 48,000
                                          Total = 63,000 credits/month

The 100k tier ($30/month) covers this with headroom. Bumping the check-in interval to 30 minutes roughly halves the heartbeat portion.

Quick reference (online check-ins enabled, 15-min interval)

Active licenses	Usage pattern	Estimated monthly credits	Recommended tier
50	4 hrs/day, daily login	~4,500	10k ($10)
200	8 hrs/day, daily login	~25,200	30k ($15)
500	8 hrs/day, daily login	~63,000	100k ($30)
1,000	8 hrs/day, daily login	~126,000	500k ($100)
5,000	8 hrs/day, daily login	~630,000	1M ($150)

These numbers scale linearly with check-in frequency. Doubling the interval halves the heartbeat column; relying on the grace period alone (the default, see below) drops it to near zero.

Credit tiers

Tier	Credits	Price	Per 1k credits
10k	10,000	$10	$1.00
30k	30,000	$15	$0.50
100k	100,000	$30	$0.30
500k	500,000	$100	$0.20
1M	1,000,000	$150	$0.15

Higher tiers offer better per-credit pricing. Choose the tier that covers your monthly estimate with a comfortable margin.

Auto-refill

Set up auto-refill to automatically purchase credits when your balance drops below a threshold. This prevents your users from experiencing no_credits failures.

Setup

Go to the Dashboard → Settings → Billing
Add a payment method (credit card via Stripe)
Enable Auto-refill
Configure:
- Tier: Which credit package to purchase (10k, 30k, 100k, etc.)
- Threshold: Trigger a purchase when balance falls below this number
- Cooldown: Minimum time between auto-refill purchases (30 minutes to 24 hours)

Recommendations

Monthly usage	Threshold	Tier	Cooldown
< 10k	2,000	10k	24 hours
10k–30k	5,000	30k	12 hours
30k–100k	10,000	100k	6 hours
100k+	20,000	100k or 500k	2 hours

Set the threshold high enough to cover your usage during the cooldown period. If you consume 1,000 credits per hour and your cooldown is 6 hours, set the threshold to at least 6,000.

Low balance alerts

Configure email alerts when your balance drops below a threshold:

Go to Settings → Billing → Alerts
Enable Low balance email
Set your alert threshold

You’ll receive an email when your balance falls below the threshold, giving you time to purchase more credits or adjust auto-refill settings.

Optimizing credit usage

Rely on the grace period (the default)

If you don’t need fast revocation enforcement, don’t enable online check-ins. The default behavior eliminates heartbeat credit consumption entirely; the SDK re-verifies the signed session locally and only makes a network call when the session expires (24 hours by default, up to 7 days via the SDK’s ttl option).

client = AuthForgeClient(
    app_id="...",
    app_secret="...",
    public_key="YOUR_PUBLIC_KEY",
    # No online_heartbeat: grace period, no check-ins, minimal credit usage
)

Credit savings: For a user running the app 8 hours/day, online check-ins at a 15-minute interval consume ~32 heartbeats ≈ 3.2 credits/day. The grace period needs at most 1 re-activation per session-TTL window (~1 credit every 24h by default). That’s roughly 3x cheaper at a 15-minute interval, and more if you check in more often.

Increase the check-in interval

If you want online check-ins but don’t need 15-minute checks, increase the interval:

client = AuthForgeClient(
    app_id="...",
    app_secret="...",
    public_key="YOUR_PUBLIC_KEY",
    online_heartbeat=True,
    heartbeat_interval=1800,  # 30 minutes instead of 15
)

Doubling the interval halves your heartbeat credit consumption.

Avoid redundant logins

If your app can open multiple windows or instances, authenticate once and share the session:

# Don't authenticate in every window/instance
# Use a lockfile or IPC to coordinate
if is_primary_instance():
    client.login(license_key)
else:
    wait_for_primary_auth()

See SDK Best Practices: Multi-instance for implementation details.

Monitoring usage

Check your current balance and transaction history in the dashboard:

Settings → Billing shows your current balance
Transaction history shows credits purchased, consumed, and auto-refilled
Usage stats show authentication volume per app

What happens when credits run out

When your account has zero credits:

SDK validate calls receive a no_credits error. The SDK treats this as a login failure.
Heartbeat milestones (every 10th check-in, if online check-ins are enabled) fail with no_credits. The SDK triggers the failure callback.

Users already authenticated continue running until their next heartbeat milestone or session expiry. They aren’t immediately disconnected.

Your users see “Authentication service temporarily unavailable”; they don’t know it’s a billing issue on your end. Set up auto-refill to prevent this.

​Credit consumption

​Estimating monthly usage

​Formula

​Example calculation

​Quick reference (online check-ins enabled, 15-min interval)

​Credit tiers

​Auto-refill

​Setup

​Recommendations

​Low balance alerts

​Optimizing credit usage

​Rely on the grace period (the default)

​Increase the check-in interval

​Avoid redundant logins

​Monitoring usage

​What happens when credits run out

Credit consumption

Estimating monthly usage

Formula

Example calculation

Quick reference (online check-ins enabled, 15-min interval)

Credit tiers

Auto-refill

Setup

Recommendations

Low balance alerts

Optimizing credit usage

Rely on the grace period (the default)

Increase the check-in interval

Avoid redundant logins

Monitoring usage

What happens when credits run out