POST /licenses/validate — Validate a Software License

This is the core public API endpoint that your distributed desktop, server, plugin, or CLI applications call at startup or runtime to verify a customer’s software license. You supply the licenseId, the productId, and the machine’s hardware identifier (hwid). Avalex checks the license status, expiration, blacklist, and slot limits, returning valid: true or valid: false along with an explicit statusCode explaining the outcome.

POST https://yourdomain.com/licenses/validate

This endpoint is public and unauthenticated. Do not embed admin JWT tokens or API secrets into distributed client software.

This endpoint is rate limited to 30 requests per minute per IP address. Exceeding this limit returns 429 Too Many Requests. Cache validation responses locally to support offline mode and avoid spamming the endpoint.

Request Body

string

required

The license key string to validate (e.g. ABCD-EFGH-IJKL-MNOP).

string

required

The product ID that this license must belong to (e.g. prod_12345).

string

required

The hardware identifier string generated on the client machine.

Example Request

curl -X POST https://yourdomain.com/licenses/validate \
  -H "Content-Type: application/json" \
  -d '{
    "licenseId": "ABCD-EFGH-IJKL-MNOP",
    "productId": "my-software-id",
    "hwid": "HWID-A1B2-C3D4-E5F6"
  }'

Response — 200 OK

boolean

required

true if all validation checks passed; false if the license is invalid, expired, blacklisted, or slot limits are exceeded.

string

Machine-readable status code explaining the exact outcome of the validation check.

Success Response Example

{
  "valid": true,
  "statusCode": "VALID"
}

Failure Response Example

{
  "valid": false,
  "statusCode": "EXPIRED"
}

Status Codes Reference

`statusCode`	`valid`	Description
`VALID`	`true`	License is active, verified, and bound to the client IP and HWID.
`NOT_FOUND`	`false`	License key does not exist in the database.
`DISABLED`	`false`	License has been manually disabled or revoked by an administrator.
`BLACKLISTED`	`false`	The requesting IP address or HWID is on the global blacklist.
`PRODUCT_MISMATCH`	`false`	The license key exists, but belongs to a different product ID.
`EXPIRED`	`false`	The license expiration date (`expiresAtEpochMillis`) has passed.
`OVERUSED`	`false`	Max allowed IP slots (`maxIps`) or HWID slots (`maxHwids`) have been exhausted.

Best Practices & Integration Tips

Offline Grace Period: Cache the last valid: true response securely on the client machine and allow a 24–72 hour grace period if your server is unreachable or the user is offline.

Validation Attempts Audit: Every validation request (success or failure) is logged in the Avalex Admin Portal with timestamp, IP, HWID, and status code for real-time monitoring and debugging.

Authentication

License Validation

Resources

Staff & Admin

Audit Logs

POST /licenses/validate — Validate a Software License

POST /licenses/validate — Validate a Software License

Request Body

Example Request

Response — 200 OK

Success Response Example

Failure Response Example

Status Codes Reference

Best Practices & Integration Tips

​POST /licenses/validate — Validate a Software License

​Request Body

​Example Request

​Response — 200 OK

​Success Response Example

​Failure Response Example

​Status Codes Reference

​Best Practices & Integration Tips

POST /licenses/validate — Validate a Software License

Request Body

Example Request

Response — 200 OK

Success Response Example

Failure Response Example

Status Codes Reference

Best Practices & Integration Tips