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

# Licenses API Reference

> Create, list, update, and delete license keys programmatically via the AuthForge Developer API.

## Create licenses

<ParamField path="POST" body="/v1/licenses">
  Create one or more license keys for an application.
</ParamField>

### 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](/features/unlimited-seats). |
| `label`              | string         | No       | Optional label for your records (max 128 chars)                                                                                                                                                           |

### Example: minimal

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

```bash theme={null}
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)

```json theme={null}
{
  "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

<ParamField path="GET" body="/v1/licenses">
  List all licenses for an application with cursor-based pagination.
</ParamField>

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

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

### Response (200)

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

```bash theme={null}
# 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

<ParamField path="GET" body="/v1/licenses/:licenseKey">
  Get full details for a single license including HWID bindings and label.
</ParamField>

### Example

```bash theme={null}
curl "https://api.authforge.cc/v1/licenses/A3K9-BFWX-7NP2-QHDT" \
  -H "Authorization: Bearer af_live_your_key"
```

### Response (200)

```json theme={null}
{
  "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

<ParamField path="PUT" body="/v1/licenses/:licenseKey">
  Perform an action on a license: revoke, activate, extend expiration, or reset HWID bindings.
</ParamField>

### 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 will fail validation on their next heartbeat or login attempt.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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)

```json theme={null}
{
  "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

<ParamField path="DELETE" body="/v1/licenses/:licenseKey">
  Permanently delete a license. This cannot be undone.
</ParamField>

### Example

```bash theme={null}
curl -X DELETE https://api.authforge.cc/v1/licenses/A3K9-BFWX-7NP2-QHDT \
  -H "Authorization: Bearer af_live_your_key"
```

### Response (200)

```json theme={null}
{ "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                        |