> ## 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.

# Managing Credits

> Understand credit consumption, estimate monthly usage, and optimize your AuthForge spending.

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

1. Go to the [Dashboard](https://app.authforge.cc/dashboard) → **Settings → Billing**
2. Add a payment method (credit card via Stripe)
3. Enable **Auto-refill**
4. 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:

1. Go to **Settings → Billing → Alerts**
2. Enable **Low balance email**
3. 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`).

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
# 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](/sdk/best-practices#multi-instance-and-multi-window) 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:

1. **SDK validate calls** receive a `no_credits` error. The SDK treats this as a login failure.
2. **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.

<Warning>
  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.
</Warning>