Documentation Index
Fetch the complete documentation index at: https://docs.authforge.cc/llms.txt
Use this file to discover all available pages before exploring further.
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 |
Estimating monthly usage
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
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) |
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 |
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 |
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
)
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
)
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()
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.
