Licenses API Reference

Create licenses

Create one or more license keys for an application.

Request body

Field	Type	Required	Description
`appId`	string	Yes	The application to issue licenses for
`quantity`	integer	No	Number of licenses to create (1–100, default 1)
`expiresAt`	string \| null	No	ISO 8601 expiration date, or `null` for lifetime
`maxHwidSlots`	integer	No	Max devices per license (1–16, default 1). Ignored when `unlimitedHwidSlots` is `true`.
`unlimitedHwidSlots`	boolean	No	When `true`, mark these licenses as shared “unlimited-seat” keys. The server skips seat enforcement and never returns `hwid_mismatch` for them. See Unlimited-seat licenses.
`label`	string	No	Optional label for your records (max 128 chars)

Example: minimal

curl -X POST https://api.authforge.cc/v1/licenses \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"appId": "YOUR_APP_ID", "quantity": 1}'

Example: all options

curl -X POST https://api.authforge.cc/v1/licenses \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "YOUR_APP_ID",
    "quantity": 5,
    "expiresAt": "2026-12-31T23:59:59Z",
    "maxHwidSlots": 2,
    "label": "Stripe order #12345"
  }'

Response (201)

{
  "licenses": [
    {
      "licenseKey": "A3K9-BFWX-7NP2-QHDT",
      "appId": "YOUR_APP_ID",
      "status": "active",
      "expiresAt": "2026-12-31T23:59:59Z",
      "maxHwidSlots": 2,
      "createdAt": "2026-04-09T22:00:00.000Z"
    }
  ]
}

Errors

HTTP	Code	Cause
400	`bad_request`	Invalid or missing parameters
402	`no_credits`	Insufficient credits
403	`forbidden`	The app doesn’t belong to your account

List licenses

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

Query parameters

Param	Type	Required	Description
`appId`	string	Yes	The application to list licenses for
`limit`	integer	No	Results per page (1–200, default 50)
`cursor`	string	No	Pagination cursor from a previous response

Example

curl "https://api.authforge.cc/v1/licenses?appId=YOUR_APP_ID&limit=50" \
  -H "Authorization: Bearer af_live_your_key"

Response (200)

{
  "licenses": [
    {
      "licenseKey": "A3K9-BFWX-7NP2-QHDT",
      "appId": "YOUR_APP_ID",
      "status": "active",
      "expiresAt": "2026-12-31T23:59:59Z",
      "maxHwidSlots": 2,
      "hwidList": [],
      "createdAt": "2026-04-09T22:00:00.000Z"
    }
  ],
  "cursor": null
}

Pagination

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

# First page
curl "https://api.authforge.cc/v1/licenses?appId=YOUR_APP_ID&limit=100" \
  -H "Authorization: Bearer af_live_your_key"

# Next page (use cursor from previous response)
curl "https://api.authforge.cc/v1/licenses?appId=YOUR_APP_ID&limit=100&cursor=eyJsaW..." \
  -H "Authorization: Bearer af_live_your_key"

Get a license

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

Example

curl "https://api.authforge.cc/v1/licenses/A3K9-BFWX-7NP2-QHDT" \
  -H "Authorization: Bearer af_live_your_key"

Response (200)

{
  "licenseKey": "A3K9-BFWX-7NP2-QHDT",
  "appId": "YOUR_APP_ID",
  "status": "active",
  "expiresAt": "2026-12-31T23:59:59Z",
  "maxHwidSlots": 2,
  "hwidList": ["abc123-hwid-fingerprint"],
  "hwid": null,
  "label": "Stripe order #12345",
  "createdAt": "2026-04-09T22:00:00.000Z"
}

Errors

HTTP	Code	Cause
403	`forbidden`	The license’s app doesn’t belong to your account
404	`not_found`	License key doesn’t exist

Update a license

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

Request body

Field	Type	Required	Description
`action`	string	Yes	One of: `revoke`, `activate`, `extend`, `reset-hwid`
`expiresAt`	string	For `extend`	New ISO 8601 expiration date (required when action is `extend`)

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.

curl -X PUT https://api.authforge.cc/v1/licenses/A3K9-BFWX-7NP2-QHDT \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "revoke"}'

Re-activate a revoked license

Restores a previously revoked license back to active status.

curl -X PUT https://api.authforge.cc/v1/licenses/A3K9-BFWX-7NP2-QHDT \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "activate"}'

Extend expiration

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

curl -X PUT https://api.authforge.cc/v1/licenses/A3K9-BFWX-7NP2-QHDT \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "extend", "expiresAt": "2027-06-30T23:59:59Z"}'

Reset HWID bindings

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

curl -X PUT https://api.authforge.cc/v1/licenses/A3K9-BFWX-7NP2-QHDT \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "reset-hwid"}'

Response (200)

{
  "ok": true,
  "license": {
    "licenseKey": "A3K9-BFWX-7NP2-QHDT",
    "appId": "YOUR_APP_ID",
    "status": "revoked",
    "expiresAt": "2026-12-31T23:59:59Z",
    "maxHwidSlots": 2,
    "hwidList": [],
    "createdAt": "2026-04-09T22:00:00.000Z"
  }
}

Delete a license

Permanently delete a license. This cannot be undone.

Example

curl -X DELETE https://api.authforge.cc/v1/licenses/A3K9-BFWX-7NP2-QHDT \
  -H "Authorization: Bearer af_live_your_key"

Response (200)

{ "ok": true }

Errors

HTTP	Code	Cause
403	`forbidden`	The license’s app doesn’t belong to your account
404	`not_found`	License key doesn’t exist

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

Field	Type	Required	Description
`expiresAt`	string or `null`	Yes	ISO 8601 file expiry. Must be in the future and on or before the license expiry. `null` mints a lifetime file and is only accepted for licenses without an expiry.
`hwidMode`	string	Yes	`bound` (verify only on listed HWIDs, recommended) or `any` (verify on any machine).
`hwids`	string[]	For `bound`	1 to 16 HWIDs. Collect them with the SDK’s `getHwid()` on the target machine, or reuse the license’s `hwidList`.
`allowUnbound`	boolean	For `any`	Must be `true` to mint an unbound file. Anyone who copies an unbound file has a working license.

Headers

Header	Required	Description
`Idempotency-Key`	Recommended	Any unique string (a UUID is ideal), same header as `POST /v1/licenses`. A retry with the same key, license and app within 24 hours returns the identical file with HTTP `200` and `meta.idempotentReplay: true`, and is not charged again. A duplicate that arrives while the first request is still running gets `409 idempotency_in_flight`; retry shortly. Without the header every request is a new, charged mint.

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

curl -X POST https://api.authforge.cc/v1/licenses/A3K9-BFWX-7NP2-QHDT/offline-files \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5c1d5f4e-9b62-4d1a-8f7e-2b0d6a7c3e11" \
  -d '{
    "expiresAt": "2026-12-10T00:00:00Z",
    "hwidMode": "bound",
    "hwids": ["3f1c9a0e...e9a2"]
  }'

Example: unbound (explicit acknowledgement)

curl -X POST https://api.authforge.cc/v1/licenses/A3K9-BFWX-7NP2-QHDT/offline-files \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "expiresAt": "2026-10-11T00:00:00Z", "hwidMode": "any", "allowUnbound": true }'

Response (201)

{
  "file": "-----BEGIN AUTHFORGE LICENSE-----\nVersion: 1\nApp-Id: YOUR_APP_ID\nLicense: A3K9-BFWX-7NP2-QHDT\nKey-Id: 8c9e...\nExpires-At: 2026-12-10T00:00:00.000Z\n\neyJ2IjoxLCJ0eXAiOiJhdXRoZm9yZ2UtbGljZW5zZSIs...\n-----END AUTHFORGE LICENSE-----\n-----BEGIN AUTHFORGE SIGNATURE-----\nOUi4frE6...\n-----END AUTHFORGE SIGNATURE-----\n",
  "fileName": "A3K9-BFWX-7NP2-QHDT.authforge",
  "meta": {
    "jti": "6b1f0c2a-...",
    "licenseKey": "A3K9-BFWX-7NP2-QHDT",
    "appId": "YOUR_APP_ID",
    "issuedAt": "2026-09-11T17:00:00.000Z",
    "expiresAt": "2026-12-10T00:00:00.000Z",
    "hwidPolicy": { "mode": "bound", "hwids": ["3f1c9a0e...e9a2"] },
    "kid": "8c9e...",
    "fileSha256": "…",
    "source": "developer-api",
    "actorId": "…",
    "apiKeyId": "…",
    "version": 1,
    "creditsCharged": 1,
    "idempotentReplay": false,
    "historyRecorded": true
  }
}

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

Field	Description
`meta.idempotentReplay`	`false` on a fresh mint (`201`), `true` when the response replays an earlier mint with the same `Idempotency-Key` (`200`).
`meta.historyRecorded`	`false` when the credit was charged and the file signed but the mint-history row could not be written. The file is still returned and the audit log still records the mint. Keep the file; retry only with the same `Idempotency-Key`.
`warnings`	Optional array, present only on partial failures. Currently `["history_not_recorded"]`, paired with `meta.historyRecorded: false`.

Errors

HTTP	Code	Cause
400	`bad_request`	Body failed schema validation (for example `hwidMode: "bound"` without `hwids`)
400	`expiry_in_past`	`expiresAt` is not a valid future timestamp
400	`expiry_after_license`	`expiresAt` is later than the license expiry
400	`lifetime_requires_perpetual_license`	`expiresAt: null` on a license that has an expiry
400	`unbound_not_allowed`	`hwidMode: "any"` without `allowUnbound: true`
400	`invalid_hwids`	`hwidMode: "bound"` but every HWID is empty or whitespace after trimming
400	`too_many_hwids`	More than 16 distinct HWIDs
402	`no_credits`	Insufficient credits; nothing was signed
403	`forbidden` / `insufficient_scope`	Not your license, or the key lacks `write:licenses`
404	`not_found`	License key doesn’t exist
409	`license_not_active`	License is revoked
409	`license_expired`	License has expired
409	`app_disabled`	App is paused
409	`idempotency_in_flight`	A request with the same `Idempotency-Key` is still running; retry shortly
409	`idempotency_replay_unavailable`	The app signing key changed since the first mint, so the original file cannot be reproduced; mint again with a new key
429	`rate_limited`	More than 30 mints/minute per account or 10/minute per license
429	`burn_cap`	App hourly/daily credit burn cap reached

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.

curl https://api.authforge.cc/v1/licenses/A3K9-BFWX-7NP2-QHDT/offline-files \
  -H "Authorization: Bearer af_live_your_key"

Response (200)

{
  "files": [
    {
      "jti": "6b1f0c2a-...",
      "licenseKey": "A3K9-BFWX-7NP2-QHDT",
      "appId": "YOUR_APP_ID",
      "issuedAt": "2026-09-11T17:00:00.000Z",
      "expiresAt": "2026-12-10T00:00:00.000Z",
      "hwidPolicy": { "mode": "bound", "hwids": ["3f1c9a0e...e9a2"] },
      "kid": "8c9e...",
      "fileSha256": "…",
      "source": "developer-api",
      "actorId": "…",
      "apiKeyId": "…",
      "version": 1,
      "creditsCharged": 1
    }
  ],
  "truncated": false,
  "limit": 100
}

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.

​Create licenses

​Request body

​Example: minimal

​Example: all options

​Response (201)

​Errors

​List licenses

​Query parameters

​Example

​Response (200)

​Pagination

​Get a license

​Example

​Response (200)

​Errors

​Update a license

​Request body

​Revoke a license

​Re-activate a revoked license

​Extend expiration

​Reset HWID bindings

​Response (200)

​Delete a license

​Example

​Response (200)

​Errors

​Offline license files

​Mint an offline license file

​Request body

​Headers

​Example: bound, 90 days

​Example: unbound (explicit acknowledgement)

​Response (201)

​Errors

​List offline file mint history

​Response (200)

Create licenses

Request body

Example: minimal

Example: all options

Response (201)

Errors

List licenses

Query parameters

Example

Response (200)

Pagination

Get a license

Example

Response (200)

Errors

Update a license

Request body

Revoke a license

Re-activate a revoked license

Extend expiration

Reset HWID bindings

Response (200)

Delete a license

Example

Response (200)

Errors

Offline license files

Mint an offline license file

Request body

Headers

Example: bound, 90 days

Example: unbound (explicit acknowledgement)

Response (201)

Errors

List offline file mint history

Response (200)