Skip to main content
Version gating lets you control which versions of your software are permitted to run under a given license. When enabled, the validate endpoint returns version information alongside the standard validation result.
Want to test version-aware validation live? Use the Validate API playground and send a version value in the request body.

​
Requirements

Version gating is available on paid plans where the product version module is enabled. Enable it for your product in the KeyPort dashboard.

​
Sending a version in the validate request

To use version gating, include a version field in your POST /api/v1/validate request body:
​
version
string
The version of your software making the validation request (e.g. "2.1.0"). If omitted, KeyPort falls back to the product’s current version.
{
  "license_key": "YOUR_LICENSE_KEY",
  "version": "2.1.0"
}

​
Version response fields

When the version module is enabled, the validate response includes:
​
version
string
The version that was evaluated. Returns null if the version module is disabled.
​
version_valid
boolean
Whether the evaluated version is valid for this license. Returns null if the version module is disabled.
{
  "version": "2.1.0",
  "version_valid": true
}

​
Version gating flow

The product version timeline and license pinning rules work together. Product-level version state decides whether a release is globally allowed, while license-level pinning can narrow that down further for a specific customer.
  1. App sends version
POST /api/v1/validate
Example payload:
Then
  1. KeyPort checks product version state
VersionPlatform stateResult
2.0.xAllowedCan continue
2.1.xAllowedCan continue
2.2.xDeprecatedStill valid
2.3.xLatestValid
2.4.xBlocked or missingversion_valid: false
Then
  1. License pinning applies for this customer
Example license rule: >=2.1 <2.4
That means this customer can use 2.1.x, 2.2.x, and 2.3.x, but not 2.0.x or anything at 2.4.x and above.
Then
  1. Validate response
version_valid is only true when the version is allowed by the product and also allowed by the license rule for that customer.

​
How to read this flow

  • Step 1 is the input from your app. Your software sends the version it is currently running.
  • Step 2 is the product-wide rule. KeyPort checks whether that release is allowed, deprecated, latest, blocked, or missing from your configured version list.
  • Step 3 is the customer-specific rule. A license can be pinned to one exact version or to a range such as >=2.1 <2.4.
  • Step 4 is the final result returned by the API. version_valid is only true when both the product-level rule and the license-level rule allow the same version.

​
What each state means

StateMeaning
AllowedThe version is approved at the product level and can continue to license pinning checks.
DeprecatedThe version is old but still accepted. Validation can still succeed.
LatestThe current recommended release for the product.
Blocked or missingThe version is not allowed, or it does not exist in the version records. version_valid becomes false.

​
Simple example

If your product allows 2.0.x to 2.3.x, but one customer’s license is pinned to >=2.1 <2.4:
  • 2.0.5 fails for that customer even though the product still allows it
  • 2.2.0 passes because both checks allow it
  • 2.4.0 fails because the product blocks or does not recognize it

​
How version validation works

KeyPort determines version_valid based on the version record and any pinning rules configured on the license:
  • If the version module is disabled, both version and version_valid are null.
  • If you don’t send a version, KeyPort falls back to the product’s current version.
  • If the referenced version record is missing or blocked, version_valid is false.
  • License version pinning applies on top of the product’s version state. Use version_pin_mode and version_range on a license to allow only exact or ranged versions for that specific customer.
License-level pinning is more restrictive than product-level version state. A version that is valid at the product level can still be rejected if it falls outside a license’s pinned range.

​
When to use version gating

Use version gating when you need to:
  • Prevent customers from running deprecated or unsupported versions
  • Restrict specific licenses to a particular version or version range
  • Roll out new versions gradually by controlling which licenses permit them