# AuthForge

> Credit-based software licensing API for developers. Validate license keys with hardware binding (HWID), Ed25519-signed sessions with an offline-tolerant grace period, optional online check-ins, and cloud-minted signed license files (`.authforge`) for air-gapped machines.

This file is an index of the AuthForge documentation, optimized for AI agents. Append `.md` to any docs URL to fetch its plain-markdown version (e.g. `https://docs.authforge.cc/api/licenses.md`).

For tools that ingest docs in bulk, the full documentation is available as a single file at `https://docs.authforge.cc/llms-full.txt`.

For tools that support the Model Context Protocol, an MCP server is hosted at `https://docs.authforge.cc/mcp` — adding it as a connector lets the agent search and fetch docs pages as tool calls.

## Two ways to use AuthForge

**Embedding (SDK):** the customer's application validates its own license at runtime. Use a language SDK. Each SDK repo ships an `AGENTS.md` reference for AI coding agents in its repository root.

**Integration (Developer API):** your backend creates, modifies, and reacts to licenses server-to-server. Use the `/v1/*` REST API. Most common shape: payment succeeds → create license → email key to customer; refund happens → revoke license.

## Core concepts

- Apps have an **App ID** (public), **App Secret** (private; authenticates `/auth/validate` calls from the SDK), and an **Ed25519 public key** (SDKs verify signed API responses)
- License keys are formatted `XXXX-XXXX-XXXX-XXXX`
- Each license has 1–16 HWID slots, optional expiry, and a status (`active`, `revoked`, `expired`)
- Default flow: activate online via `/auth/validate`, then run through the **grace period** on the signed session with no further network calls; the SDK re-verifies the session locally
- The grace period equals the session TTL: default 24h, clamped server-side to `[1h, 7d]`, configurable via the SDK `ttl` option, preserved across heartbeat refreshes
- **Online check-ins** (optional, `online_heartbeat` / `onlineHeartbeat`): periodic `/auth/heartbeat` calls for fast revocation and concurrent-use detection; default interval 15 minutes; each check-in refreshes the session
- Legacy `heartbeat_mode: "SERVER" | "LOCAL"` is deprecated: LOCAL = the default grace-period behavior (remove the option), SERVER = enable online check-ins
- **Offline license files** (`.authforge`, separate mode, SDK 1.2.0+): an operator mints a signed file in the dashboard or via `POST /v1/licenses/{licenseKey}/offline-files`; the SDK verifies it locally with `loginFromFile` using only the app public key, app id, and machine HWID — never the App Secret, never contacting AuthForge. Collect the HWID as an **activation request** (`.authforge-request`) rather than a pasted string. Air-gapped builds should omit the secret. Issued files stay valid until their own expiry; online revoke does not reach them. Default remains online activate + grace period; use offline files only when machines are truly air-gapped
- Successful validation costs 1 credit; 10 successful heartbeats cost 1 credit (billed on every 10th); minting an offline license file costs 1 credit (verifying is free)
- Server responses are Ed25519-signed; SDKs verify automatically
- Nonce replay detection applies to `/auth/validate` only, not heartbeats
- Heartbeats are rate-limited 6/min per license (no per-IP limit); `/auth/validate` is rate-limited per IP+license

## Hosts

- `https://api.authforge.cc` — Developer API (`/v1/*`). Bearer auth (`af_live_*` API keys)
- `https://auth.authforge.cc` — Public SDK runtime: `/auth/validate`, `/auth/heartbeat`, `/auth/selfban`. No auth header (signed payloads)

## Getting started

- Introduction: https://docs.authforge.cc/introduction.md
- Quickstart: https://docs.authforge.cc/quickstart.md
- Concepts: https://docs.authforge.cc/concepts.md
- FAQ: https://docs.authforge.cc/faq.md

## Developer API reference (server-to-server integrations)

- Overview & authentication: https://docs.authforge.cc/api/overview.md
- Licenses (create, list, get, update, delete, mint offline license files): https://docs.authforge.cc/api/licenses.md
- Variables (feature flags, per-app and per-license): https://docs.authforge.cc/api/variables.md
- Webhooks (CRUD + signature verification): https://docs.authforge.cc/api/webhooks.md
- Security (HWID/IP block & allow lists): https://docs.authforge.cc/api/security.md
- Error codes: https://docs.authforge.cc/api/errors.md

## Integration guides

- Build your own integration (general patterns): https://docs.authforge.cc/guides/custom-integration.md
- Stripe (checkout → license): https://docs.authforge.cc/guides/stripe.md
- Lemon Squeezy: https://docs.authforge.cc/guides/lemon.md
- Subscriptions (renewals, expiry extension): https://docs.authforge.cc/guides/subscriptions.md
- Tiered licensing: https://docs.authforge.cc/guides/tiered-licensing.md
- Feature flags via license variables: https://docs.authforge.cc/guides/feature-flags.md
- Telegram bot dispenser: https://docs.authforge.cc/guides/telegram-bot.md
- Discord bot dispenser: https://docs.authforge.cc/guides/discord-bot.md
- HWID override (identity-based binding): https://docs.authforge.cc/guides/hwid-override.md
- Finding a machine's HWID: https://docs.authforge.cc/guides/finding-hwid.md
- Activation requests (`.authforge-request`, how the customer sends a HWID): https://docs.authforge.cc/guides/activation-requests.md
- Developing with AI coding agents: https://docs.authforge.cc/guides/ai-development.md

## SDKs (embedding licensing in an end-user app)

- SDK overview: https://docs.authforge.cc/sdk/overview.md
- Python: https://docs.authforge.cc/sdk/python.md → repo: https://github.com/AuthForgeCC/authforge-python
- C#: https://docs.authforge.cc/sdk/csharp.md → repo: https://github.com/AuthForgeCC/authforge-csharp
- C++: https://docs.authforge.cc/sdk/cpp.md → repo: https://github.com/AuthForgeCC/authforge-cpp
- Rust: https://docs.authforge.cc/sdk/rust.md → repo: https://github.com/AuthForgeCC/authforge-rust
- Go: https://docs.authforge.cc/sdk/go.md → repo: https://github.com/AuthForgeCC/authforge-go
- Node.js: https://docs.authforge.cc/sdk/node.md → repo: https://github.com/AuthForgeCC/authforge-node
- SDK best practices: https://docs.authforge.cc/sdk/best-practices.md

Each SDK repository contains an `AGENTS.md` at its root — the canonical reference for AI coding agents wiring the SDK into a project.

## Features

- Commerce (built-in Stripe & Lemon Squeezy): https://docs.authforge.cc/features/commerce.md
- Customer portal: https://docs.authforge.cc/features/portal.md
- Variables: https://docs.authforge.cc/features/variables.md
- Webhooks: https://docs.authforge.cc/features/webhooks.md
- Security: https://docs.authforge.cc/features/security.md
- HWID locking: https://docs.authforge.cc/features/hwid-locking.md
- HWID override: https://docs.authforge.cc/features/hwid-override.md
- Offline license files (.authforge, air-gapped machines): https://docs.authforge.cc/features/offline-license-files.md
- Unlimited seats: https://docs.authforge.cc/features/unlimited-seats.md
- Low-latency validation: https://docs.authforge.cc/features/low-latency-validation.md
- Unlimited applications: https://docs.authforge.cc/features/unlimited-applications.md

## Best practices

- Security: https://docs.authforge.cc/best-practices/security.md
- UX patterns: https://docs.authforge.cc/best-practices/ux-patterns.md
- Credit management: https://docs.authforge.cc/best-practices/credit-management.md
- Offline licensing (storing, refreshing and enforcing .authforge files): https://docs.authforge.cc/best-practices/offline-licensing.md

## Account

- Sign up / dashboard: https://app.authforge.cc/auth