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	1 credit

Failed validations (invalid key, expired, revoked) do not consume credits. Only successful authentications are billed. Heartbeat credits are debited on every 10th successful call.

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

Example calculation

Suppose you have:

500 active licenses
Users log in once per day on average
Users run the app 8 hours per day
Heartbeat interval: 15 minutes (default)

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 heartbeat interval to 30 minutes roughly halves the heartbeat portion.

Quick reference (SERVER mode, 15-min heartbeat)

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 heartbeat frequency. Doubling the interval halves the heartbeat column; switching to LOCAL mode (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

Use LOCAL heartbeat mode

If you don’t need instant revocation enforcement, switch to LOCAL heartbeat mode. This eliminates heartbeat credit consumption almost entirely; the SDK only makes a network call when the session token expires (24 hours by default, up to 7 days if the SDK set a custom ttlSeconds).

client = AuthForgeClient(
    app_id="...",
    app_secret="...",
    heartbeat_mode="LOCAL",  # Minimal credit usage
)

Credit savings: For a user running the app 8 hours/day, SERVER mode at a 15-minute interval consumes ~32 heartbeats ≈ 3.2 credits/day. LOCAL mode needs at most 1 re-validate per session-TTL-window (~1 credit every 24h by default). That’s roughly 3x cheaper at a 15-minute interval and scales much further if you shorten the interval.

Increase heartbeat interval

If you want SERVER mode but don’t need 15-minute checks, increase the interval:

client = AuthForgeClient(
    app_id="...",
    app_secret="...",
    heartbeat_mode="SERVER",
    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 heartbeat) 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 (SERVER mode, 15-min heartbeat)

​Credit tiers

​Auto-refill

​Setup

​Recommendations

​Low balance alerts

​Optimizing credit usage

​Use LOCAL heartbeat mode

​Increase heartbeat interval

​Avoid redundant logins

​Monitoring usage

​What happens when credits run out

Credit consumption

Estimating monthly usage

Formula

Example calculation

Quick reference (SERVER mode, 15-min heartbeat)

Credit tiers

Auto-refill

Setup

Recommendations

Low balance alerts

Optimizing credit usage

Use LOCAL heartbeat mode

Increase heartbeat interval

Avoid redundant logins

Monitoring usage

What happens when credits run out