> For the complete documentation index, see [llms.txt](https://docs.papelship.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.papelship.com/qpapel-web-api-reference/license-keys.md).

# License Keys

Programmatic management of customer license keys, hardware ID bindings, activations, and bans.

## List License Keys

> Retrieve a paginated and filterable list of active, expired, or banned license keys.

```json
{"openapi":"3.0.3","info":{"title":"qPapel Protection Web API","version":"1.0.0"},"tags":[{"name":"License Keys","description":"Programmatic management of customer license keys, hardware ID bindings, activations, and bans."}],"servers":[{"url":"https://papelship.com/api/qpapel/v1","description":"Production Server"}],"security":[{"BearerAuth":[]},{"ApiKeyHeader":[]},{"ApiKeyHeaderLegacy":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API_KEY","description":"Standard HTTP Bearer token authentication header (e.g. `Authorization: Bearer pk_live_...`)."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Custom header API key authentication parameter (`x-api-key: pk_live_...`)."},"ApiKeyHeaderLegacy":{"type":"apiKey","in":"header","name":"api-key","description":"Legacy custom header API key fallback parameter (`api-key: pk_live_...`)."}},"schemas":{"LicenseKey":{"type":"object","properties":{"id":{"type":"integer"},"key_value":{"type":"string"},"product":{"type":"string"},"start_time":{"type":"string","format":"date-time","nullable":true},"end_time":{"type":"string","format":"date-time","nullable":true},"used_count":{"type":"integer"},"max_uses":{"type":"integer"},"is_banned":{"type":"boolean"},"is_active":{"type":"boolean"},"note":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"StandardErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}},"responses":{"UnauthorizedError":{"description":"Authentication failed. Missing or invalid developer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"InternalServerError":{"description":"Server error occurred during operation processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}}},"paths":{"/keys":{"get":{"tags":["License Keys"],"summary":"List License Keys","description":"Retrieve a paginated and filterable list of active, expired, or banned license keys.","operationId":"listLicenseKeys","parameters":[{"name":"scope","in":"query","description":"Scope filter for key ownership: 'me' (own keys), 'resellers', or 'all'.","schema":{"type":"string","enum":["me","resellers","all"],"default":"me"}},{"name":"product","in":"query","description":"Filter keys by specific product cheat_value or product ID.","schema":{"type":"string"}},{"name":"search","in":"query","description":"Case-insensitive search string matching license key sequence or user notes.","schema":{"type":"string"}},{"name":"expiresInDays","in":"query","description":"Filter keys scheduled to expire within the specified number of days.","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","description":"Number of records to return per page.","schema":{"type":"integer","default":25,"minimum":1,"maximum":1000}},{"name":"offset","in":"query","description":"Number of records to skip for pagination.","schema":{"type":"integer","default":0,"minimum":0}},{"name":"sortBy","in":"query","description":"Field name to sort results by.","schema":{"type":"string","enum":["created_at","end_time","used_count","key_value"],"default":"created_at"}},{"name":"sortOrder","in":"query","description":"Sort ordering direction.","schema":{"type":"string","enum":["ASC","DESC"],"default":"DESC"}}],"responses":{"200":{"description":"Successful retrieval of license keys.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"keys":{"type":"array","items":{"$ref":"#/components/schemas/LicenseKey"}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Create License Key

> Generate a new license key with custom duration, HWID binding rules, activation modes, and optional metadata notes.

```json
{"openapi":"3.0.3","info":{"title":"qPapel Protection Web API","version":"1.0.0"},"tags":[{"name":"License Keys","description":"Programmatic management of customer license keys, hardware ID bindings, activations, and bans."}],"servers":[{"url":"https://papelship.com/api/qpapel/v1","description":"Production Server"}],"security":[{"BearerAuth":[]},{"ApiKeyHeader":[]},{"ApiKeyHeaderLegacy":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API_KEY","description":"Standard HTTP Bearer token authentication header (e.g. `Authorization: Bearer pk_live_...`)."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Custom header API key authentication parameter (`x-api-key: pk_live_...`)."},"ApiKeyHeaderLegacy":{"type":"apiKey","in":"header","name":"api-key","description":"Legacy custom header API key fallback parameter (`api-key: pk_live_...`)."}},"responses":{"BadRequestError":{"description":"Invalid request body or query parameter structure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"UnauthorizedError":{"description":"Authentication failed. Missing or invalid developer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"ForbiddenError":{"description":"Insufficient permissions or subscription tier limits reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}},"schemas":{"StandardErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}},"paths":{"/keys":{"post":{"tags":["License Keys"],"summary":"Create License Key","description":"Generate a new license key with custom duration, HWID binding rules, activation modes, and optional metadata notes.","operationId":"createLicenseKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product_id","days"],"properties":{"product_id":{"type":"integer","description":"Unique numeric database ID of the target product."},"days":{"type":"integer","description":"Validity duration in days (or hours if key_type is hour_limited)."},"key_type":{"type":"string","description":"Licensing behavior model.","enum":["time_limited","single_use","multi_use","time_restricted","hour_limited"],"default":"time_limited"},"note":{"type":"string","description":"Internal reference notes or customer identifier."},"max_uses":{"type":"integer","description":"Maximum activations allowed before key locks out.","default":1},"bind_hwid":{"type":"boolean","description":"Enforce hardware ID locking on first machine activation.","default":true},"auto_start":{"type":"boolean","description":"If true, expiry countdown begins upon generation rather than on first client use.","default":false},"amount":{"type":"integer","description":"Quantity of keys to generate in bulk (max 100).","default":1}}}}}},"responses":{"200":{"description":"License key created successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"key":{"type":"string"},"id":{"type":"integer"},"type":{"type":"string"},"product":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"}}}}}}
```

## Delete License Key

> Permanently remove a license key from the system.

```json
{"openapi":"3.0.3","info":{"title":"qPapel Protection Web API","version":"1.0.0"},"tags":[{"name":"License Keys","description":"Programmatic management of customer license keys, hardware ID bindings, activations, and bans."}],"servers":[{"url":"https://papelship.com/api/qpapel/v1","description":"Production Server"}],"security":[{"BearerAuth":[]},{"ApiKeyHeader":[]},{"ApiKeyHeaderLegacy":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API_KEY","description":"Standard HTTP Bearer token authentication header (e.g. `Authorization: Bearer pk_live_...`)."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Custom header API key authentication parameter (`x-api-key: pk_live_...`)."},"ApiKeyHeaderLegacy":{"type":"apiKey","in":"header","name":"api-key","description":"Legacy custom header API key fallback parameter (`api-key: pk_live_...`)."}},"schemas":{"StandardSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"StandardErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}},"responses":{"UnauthorizedError":{"description":"Authentication failed. Missing or invalid developer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"NotFoundError":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}}},"paths":{"/keys/{id}":{"delete":{"tags":["License Keys"],"summary":"Delete License Key","description":"Permanently remove a license key from the system.","operationId":"deleteLicenseKey","parameters":[{"name":"id","in":"path","required":true,"description":"Unique database ID of the license key.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Key deleted successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccessResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```

## Ban License Key

> Revoke license validity and record a disciplinary ban reason.

```json
{"openapi":"3.0.3","info":{"title":"qPapel Protection Web API","version":"1.0.0"},"tags":[{"name":"License Keys","description":"Programmatic management of customer license keys, hardware ID bindings, activations, and bans."}],"servers":[{"url":"https://papelship.com/api/qpapel/v1","description":"Production Server"}],"security":[{"BearerAuth":[]},{"ApiKeyHeader":[]},{"ApiKeyHeaderLegacy":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API_KEY","description":"Standard HTTP Bearer token authentication header (e.g. `Authorization: Bearer pk_live_...`)."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Custom header API key authentication parameter (`x-api-key: pk_live_...`)."},"ApiKeyHeaderLegacy":{"type":"apiKey","in":"header","name":"api-key","description":"Legacy custom header API key fallback parameter (`api-key: pk_live_...`)."}},"schemas":{"StandardSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"StandardErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}},"responses":{"BadRequestError":{"description":"Invalid request body or query parameter structure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"UnauthorizedError":{"description":"Authentication failed. Missing or invalid developer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"NotFoundError":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}}},"paths":{"/keys/{id}/ban":{"post":{"tags":["License Keys"],"summary":"Ban License Key","description":"Revoke license validity and record a disciplinary ban reason.","operationId":"banLicenseKey","parameters":[{"name":"id","in":"path","required":true,"description":"Unique database ID of the license key.","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","description":"Explanation for the ban action."}}}}}},"responses":{"200":{"description":"Key banned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccessResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```

## Unban License Key

> Restore active validity to a previously banned license key.

```json
{"openapi":"3.0.3","info":{"title":"qPapel Protection Web API","version":"1.0.0"},"tags":[{"name":"License Keys","description":"Programmatic management of customer license keys, hardware ID bindings, activations, and bans."}],"servers":[{"url":"https://papelship.com/api/qpapel/v1","description":"Production Server"}],"security":[{"BearerAuth":[]},{"ApiKeyHeader":[]},{"ApiKeyHeaderLegacy":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API_KEY","description":"Standard HTTP Bearer token authentication header (e.g. `Authorization: Bearer pk_live_...`)."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Custom header API key authentication parameter (`x-api-key: pk_live_...`)."},"ApiKeyHeaderLegacy":{"type":"apiKey","in":"header","name":"api-key","description":"Legacy custom header API key fallback parameter (`api-key: pk_live_...`)."}},"schemas":{"StandardSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"StandardErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}},"responses":{"UnauthorizedError":{"description":"Authentication failed. Missing or invalid developer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"NotFoundError":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}}},"paths":{"/keys/{id}/unban":{"post":{"tags":["License Keys"],"summary":"Unban License Key","description":"Restore active validity to a previously banned license key.","operationId":"unbanLicenseKey","parameters":[{"name":"id","in":"path","required":true,"description":"Unique database ID of the license key.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Key unbanned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccessResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```

## Freeze License Key

> Pause the expiration countdown on an active license key.

```json
{"openapi":"3.0.3","info":{"title":"qPapel Protection Web API","version":"1.0.0"},"tags":[{"name":"License Keys","description":"Programmatic management of customer license keys, hardware ID bindings, activations, and bans."}],"servers":[{"url":"https://papelship.com/api/qpapel/v1","description":"Production Server"}],"security":[{"BearerAuth":[]},{"ApiKeyHeader":[]},{"ApiKeyHeaderLegacy":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API_KEY","description":"Standard HTTP Bearer token authentication header (e.g. `Authorization: Bearer pk_live_...`)."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Custom header API key authentication parameter (`x-api-key: pk_live_...`)."},"ApiKeyHeaderLegacy":{"type":"apiKey","in":"header","name":"api-key","description":"Legacy custom header API key fallback parameter (`api-key: pk_live_...`)."}},"schemas":{"StandardSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"StandardErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}},"responses":{"UnauthorizedError":{"description":"Authentication failed. Missing or invalid developer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"NotFoundError":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}}},"paths":{"/keys/{id}/freeze":{"post":{"tags":["License Keys"],"summary":"Freeze License Key","description":"Pause the expiration countdown on an active license key.","operationId":"freezeLicenseKey","parameters":[{"name":"id","in":"path","required":true,"description":"Unique database ID of the license key.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Key frozen successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccessResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```

## Unfreeze License Key

> Resume the expiration countdown on a frozen license key.

```json
{"openapi":"3.0.3","info":{"title":"qPapel Protection Web API","version":"1.0.0"},"tags":[{"name":"License Keys","description":"Programmatic management of customer license keys, hardware ID bindings, activations, and bans."}],"servers":[{"url":"https://papelship.com/api/qpapel/v1","description":"Production Server"}],"security":[{"BearerAuth":[]},{"ApiKeyHeader":[]},{"ApiKeyHeaderLegacy":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API_KEY","description":"Standard HTTP Bearer token authentication header (e.g. `Authorization: Bearer pk_live_...`)."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Custom header API key authentication parameter (`x-api-key: pk_live_...`)."},"ApiKeyHeaderLegacy":{"type":"apiKey","in":"header","name":"api-key","description":"Legacy custom header API key fallback parameter (`api-key: pk_live_...`)."}},"schemas":{"StandardSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"StandardErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}},"responses":{"UnauthorizedError":{"description":"Authentication failed. Missing or invalid developer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"NotFoundError":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}}},"paths":{"/keys/{id}/freeze":{"delete":{"tags":["License Keys"],"summary":"Unfreeze License Key","description":"Resume the expiration countdown on a frozen license key.","operationId":"unfreezeLicenseKey","parameters":[{"name":"id","in":"path","required":true,"description":"Unique database ID of the license key.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Key unfrozen successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccessResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```

## Reset HWID Binding

> Clear the locked hardware fingerprint to allow user activation on a new machine.

```json
{"openapi":"3.0.3","info":{"title":"qPapel Protection Web API","version":"1.0.0"},"tags":[{"name":"License Keys","description":"Programmatic management of customer license keys, hardware ID bindings, activations, and bans."}],"servers":[{"url":"https://papelship.com/api/qpapel/v1","description":"Production Server"}],"security":[{"BearerAuth":[]},{"ApiKeyHeader":[]},{"ApiKeyHeaderLegacy":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API_KEY","description":"Standard HTTP Bearer token authentication header (e.g. `Authorization: Bearer pk_live_...`)."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Custom header API key authentication parameter (`x-api-key: pk_live_...`)."},"ApiKeyHeaderLegacy":{"type":"apiKey","in":"header","name":"api-key","description":"Legacy custom header API key fallback parameter (`api-key: pk_live_...`)."}},"schemas":{"StandardSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"StandardErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}},"responses":{"UnauthorizedError":{"description":"Authentication failed. Missing or invalid developer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"NotFoundError":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}}},"paths":{"/keys/{id}/reset-hwid":{"post":{"tags":["License Keys"],"summary":"Reset HWID Binding","description":"Clear the locked hardware fingerprint to allow user activation on a new machine.","operationId":"resetKeyHwid","parameters":[{"name":"id","in":"path","required":true,"description":"Unique database ID of the license key.","schema":{"type":"integer"}}],"responses":{"200":{"description":"HWID binding reset successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccessResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```

## Extend Key Duration

> Add additional validity days to an active license key.

```json
{"openapi":"3.0.3","info":{"title":"qPapel Protection Web API","version":"1.0.0"},"tags":[{"name":"License Keys","description":"Programmatic management of customer license keys, hardware ID bindings, activations, and bans."}],"servers":[{"url":"https://papelship.com/api/qpapel/v1","description":"Production Server"}],"security":[{"BearerAuth":[]},{"ApiKeyHeader":[]},{"ApiKeyHeaderLegacy":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API_KEY","description":"Standard HTTP Bearer token authentication header (e.g. `Authorization: Bearer pk_live_...`)."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Custom header API key authentication parameter (`x-api-key: pk_live_...`)."},"ApiKeyHeaderLegacy":{"type":"apiKey","in":"header","name":"api-key","description":"Legacy custom header API key fallback parameter (`api-key: pk_live_...`)."}},"schemas":{"StandardSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"StandardErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}},"responses":{"BadRequestError":{"description":"Invalid request body or query parameter structure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"UnauthorizedError":{"description":"Authentication failed. Missing or invalid developer API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"NotFoundError":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}}},"paths":{"/keys/{id}/add-time":{"post":{"tags":["License Keys"],"summary":"Extend Key Duration","description":"Add additional validity days to an active license key.","operationId":"addTimeToKey","parameters":[{"name":"id","in":"path","required":true,"description":"Unique database ID of the license key.","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["days"],"properties":{"days":{"type":"integer","minimum":1,"description":"Number of days to append to the license end date."}}}}}},"responses":{"200":{"description":"Duration added successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccessResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```