Skip to main content

Create licenses

Create one or more license keys for an application.

Request body

Example: minimal

Example: all options

Response (201)

Errors


List licenses

List all licenses for an application with cursor-based pagination.

Query parameters

Example

Response (200)

Pagination

If cursor is non-null, more results are available. Pass it as a query parameter in the next request:

Get a license

Get full details for a single license including HWID bindings and label.

Example

Response (200)

Errors


Update a license

Perform an action on a license: revoke, activate, extend expiration, or reset HWID bindings.

Request body

Revoke a license

Immediately disables the license. End users fail on their next activation or online check-in; apps running through the grace period without check-ins stop at session expiry. Revoking also blocks new offline license file mints, but files already minted stay valid until their own expiry.

Re-activate a revoked license

Restores a previously revoked license back to active status.

Extend expiration

Sets a new expiration date. Use for subscription renewals or granting additional time.

Reset HWID bindings

Clears all bound hardware IDs, allowing the license to be activated on new devices.

Response (200)


Delete a license

Permanently delete a license. This cannot be undone.

Example

Response (200)

Errors


Offline license files

Cloud-minted, Ed25519-signed .authforge files for machines that never connect to the internet. The SDK verifies a file locally with your app public key and the machine HWID; it never contacts AuthForge. This is a separate mode from the grace period. Read Offline license files first, especially the revocation semantics: issued files stay valid until their own expiry; revoking the license only blocks new mints.

Mint an offline license file

Mint a .authforge file for an active license. Scope write:licenses. 1 credit per successful mint (same debit path as /auth/validate, so your app’s burn caps apply); rejected mints are free.

Request body

Headers

The server never stores the file body: on a replay it re-signs the stored payload with your app key (Ed25519 is deterministic), so the bytes match the first response exactly.

Example: bound, 90 days

Example: unbound (explicit acknowledgement)

Response (201)

Write file to disk as fileName. The server stores only fileSha256, never the file body, so there is no download endpoint; if the response was lost, retry with the same Idempotency-Key within 24h to get the identical file (HTTP 200, meta.idempotentReplay: true, no extra charge).

Errors

List offline file mint history

Newest-first mint records for the license, capped at the 100 most recent (limit); truncated: true means older mints were omitted and the full trail is in the account audit log. Scope read:licenses. Returns metadata and hashes only; file bodies are never stored.

Response (200)

Use this to track which files are outstanding for a license and when each one lapses; it is the operator-side half of the re-issue workflow described in Offline licensing best practices.

Self-serve offline activation

End users can turn a license key into a lifetime, HWID-bound .authforge file with one call from your app. Read Self-serve activation first. A refund or chargeback revokes the license online but cannot reach files already issued. For a lifetime file, that means the buyer keeps the app.

Turn it on for an app

Update app settings. Scope write:apps. Send at least one field.
Returns 200 with { "ok": true }. The dashboard has the same toggle in the app’s settings.

Activate (public, called by the SDK)

Served on https://auth.authforge.cc, not api.authforge.cc. No bearer auth: the app authenticates with its App ID and App Secret, like /auth/validate. The SDK methods (activate_offline / activateOffline / ActivateOffline) call it for you and verify the result.

Request body

Checks

The server runs the same checks as /auth/validate (app and secret, nonce, app paused, access lists, license exists, active and not expired), then:
  1. The app has offlineSelfServe.enabled: true, otherwise offline_activation_disabled.
  2. The license is perpetual (no expiresAt), otherwise offline_activation_requires_perpetual.
  3. The license is seat-limited, otherwise offline_activation_requires_seats.
  4. If this HWID already holds a file for this license, the identical file is returned (200, replay: true, no charge, no seat needed).
  5. Otherwise the license must be under its machine cap (offline_activation_limit_reached), the HWID must hold or get a seat (hwid_mismatch), and you need 2 credits (no_credits / app_burn_cap_reached).
The seat bind, the machine count and the 2-credit debit commit together or not at all, so every refusal is free.

Response (201 new file, 200 existing file)

The response has no separate signature: the file is the signed artifact. Verify it with your public key, app id and the machine’s HWID before saving it; the official SDKs do this and refuse a bad file with offline_file_rejected. 201 responses carry X-RateLimit-Remaining.

Errors

See Error codes -> Self-serve activation errors for user-facing messages.

List offline machines

Machines that hold a self-serve lifetime file for this license, oldest first. Scope read:licenses. Never returns the file or its payload.

Response (200)

Release an offline machine

Frees one machine slot so the license can activate another machine, and unbinds that machine’s seat. Scope write:licenses.
The released machine’s file keeps working. Nothing can reach a file already on a customer machine. Release only when you trust the request (for example “my old PC died”). Releases are audited as license.offline_machine_released.
Returns 200 with { "ok": true }, or 404 not_found when the license has no machine with that hwidHash. The dashboard has the same action: Release in the Offline machines section of the license page.