Select programming language for code examples

linkLicenses

linkThe license object

Below you will find the various attributes for the license resource, as well as the license resource's relationships. A license is an implementation of a product's policy.

linkAttributes

  • linkdata.attributes.name

    string

    The name of the license. This can be used to distinguish licenses from eachother.

  • linkdata.attributes.key

    string, default isauto-generated

    A unique pre-determined key for the license. License keys are immutable values. Cannot be used on legacy encrypted licenses. This attribute will be automatically generated or popped from the remaining pool if left blank and the chosen scheme supports auto-generated keys. Depending on the policy's cryptographic scheme (if any), the key attribute may be required for a 'seed' dataset to embed into the final key, and the key may have other requirements that must be met regarding dataset length and formatting. The key and its signature may be base64url encoded, depending on the chosen scheme.

  • linkdata.attributes.expiry

    timestamp (ISO8601 format)

    When the license will expire. Calculated from the license's policy, i.e. time.now + policy.duration, at the time of creation and/or renewal.

  • linkdata.attributes.status

    stringread only

    The license's status, for filtering purposes and to ascertain overall status at-a-glance. An active license is a license that has been validated within the last 90 days. An expiring license is a license that is expiring within the next 3 days. This is not a replacement for validation. One of: ACTIVE, INACTIVE, EXPIRING, EXPIRED, or SUSPENDED.

  • linkdata.attributes.uses

    integer, default is0

    The license's current usage count. This can be incremented, decremented, or reset using the license's usage-related actions. Cannot exceed 2,147,483,647, which is the maximum value of a 4 byte integer.

  • linkdata.attributes.protected

    boolean, default isinherited

    Whether or not the license is protected. A protected license disallows users the ability to activate and manage machines themselves, useful in situations where you want to allow machine creation for a protected account or policy. If the license's policy is protected, they automatically inherit that value when left blank.

  • linkdata.attributes.suspended

    boolean

    Whether or not the license is suspended. A suspended license will always fail validation.

  • linkdata.attributes.floating

    booleanread only

    Whether or not the license is floating. This is inherited from the policy.

  • linkdata.attributes.concurrent

    booleanread only

    Whether or not the license is concurrent. This is inherited from the policy.

  • linkdata.attributes.scheme

    stringread only

    The cryptographic encryption/signature scheme used on the license's key. Can be used to implement offline licensing by securely storing arbitrary data within a license's key.

  • linkdata.attributes.strict

    booleanread only

    Whether or not the policy is strict. This is inherited from the policy.

  • linkdata.attributes.maxMachines

    integer

    The maximum number of machines the license can have associated with it. This is by default inherited from the policy, but can be overriden on a per-license basis.

  • linkdata.attributes.maxCores

    integer

    The maximum number of machine CPU cores the license can have associated with it. The count is the sum of all cores for the license's machines. This is by default inherited from the policy, but can be overriden on a per-license basis.

  • linkdata.attributes.maxUses

    integer

    The maximum number of uses the license is allowed to have. This is by default inherited from the policy, but can be overriden on a per-license basis.

  • linkdata.attributes.requireCheckIn

    booleanread only

    Whether or not the license will require check-in at a predefined interval to continue to pass validation i.e. if a license misses a check-in, it will be invalidated. This is inherited from the policy.

  • linkdata.attributes.lastValidated

    timestamp (ISO8601 format)read only

    When the license was last validated.

  • linkdata.attributes.lastCheckIn

    timestamp (ISO8601 format)read only

    When the license was last checked-in. This is null if the policy does not require check-ins.

  • linkdata.attributes.nextCheckIn

    timestamp (ISO8601 format)read only

    The time at which the license is required to check-in by. This is null if the policy does not require check-ins.

  • linkdata.attributes.metadata

    object<string, scalar>

    Object containing license metadata.

  • linkdata.attributes.created

    timestamp (ISO8601 format)read only

    When the license was created.

  • linkdata.attributes.updated

    timestamp (ISO8601 format)read only

    When the license was last updated.

linkRelationships

  • linkdata.relationships.account

    individual

    The account that the license belongs to.

  • linkdata.relationships.product

    individual

    The product that the license is associated with.

  • linkdata.relationships.policy

    individual

    The policy that the license implements.

  • linkdata.relationships.user

    individual

    The user that owns the license.

  • linkdata.relationships.machines

    collection

    The machines that the license is associated with.

Example object

{
"data": {
"id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2022-03-15T19:27:50.440Z",
"status": "ACTIVE",
"uses": 0,
"protected": false,
"suspended": false,
"scheme": null,
"encrypted": false,
"floating": false,
"concurrent": true,
"strict": false,
"maxMachines": 5,
"maxCores": 64,
"maxUses": null,
"requireCheckIn": false,
"lastValidated": "2021-03-15T19:27:50.440Z",
"lastCheckIn": null,
"nextCheckIn": null,
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 2
}
},
"tokens": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements"
}
}
}
}
}

linkCreate a license

Creates a new license resource.

License keys are immutable values. Once a license is created, its key cannot be changed. This also means that, for cryptographic keys, the dataset you choose to embed into a license key cannot be changed, and changes to the license object itself have no effect on the embedded dataset. Please take this into account when designing your embedded dataset, especially concerning expiration dates.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin, the product it belongs to, or if the license's policy is unprotected, the user it belongs to.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

linkAttributes

  • linkdata.attributes.name

    string, optional

    The name of the license. This can be used to distinguish licenses from eachother.

  • linkdata.attributes.key

    string, optional, default isauto-generated

    A unique pre-determined key for the license. License keys are immutable values. This attribute will be automatically generated or popped from the remaining pool if left blank and the chosen scheme supports auto-generated keys. Depending on the policy's cryptographic scheme (if any), the key attribute may be required for a 'seed' dataset to embed into the final key, and the key may have other requirements that must be met regarding dataset length and formatting.

  • linkdata.attributes.expiry

    timestamp (ISO8601 format), optionalprotectedProtected attributes are only available for bearers with an admin or product role.

    When the license will expire. When left blank, this will automatically be calculated based on the license's policy, i.e. time.now + policy.duration.

  • linkdata.attributes.maxMachines

    integer, optionalprotectedProtected attributes are only available for bearers with an admin or product role.

    The maximum number of machines the license can have associated with it. This is by default inherited from the policy, but can be overriden on a per-license basis. Set to null to remove an override.

  • linkdata.attributes.maxCores

    integer, optionalprotectedProtected attributes are only available for bearers with an admin or product role.

    The maximum number of machine CPU cores the license can have associated with it. The count is the sum of all cores for the license's machines. This is by default inherited from the policy, but can be overriden on a per-license basis. Set to null to remove an override.

  • linkdata.attributes.maxUses

    integer, optionalprotectedProtected attributes are only available for bearers with an admin or product role.

    The maximum number of uses the license is allowed to have. This is by default inherited from the policy, but can be overriden on a per-license basis. Set to null to remove an override.

  • linkdata.attributes.protected

    boolean, optional, default isinheritedprotectedProtected attributes are only available for bearers with an admin or product role.

    Whether or not the license is protected. A protected license disallows users the ability to activate and manage machines themselves, useful in situations where you want to allow machine creation for a protected account or policy. If the license's policy is protected, they automatically inherit that value when left blank.

  • linkdata.attributes.suspended

    boolean, optional, default isfalseprotectedProtected attributes are only available for bearers with an admin or product role.

    Whether or not the license is suspended.

  • linkdata.attributes.metadata

    object<string, scalar>, optional

    Object containing license metadata.

linkRelationships

  • linkdata.relationships.policy

    linkage<policy>, required

    The policy to implement for the license.

  • linkdata.relationships.user

    linkage<user>, optional

    The user the license is for. If ommitted, the license will be user-less. This is useful if your licensing model doesn't require a user association, or if you're managing users within your own database. If authenticated as a user, this relationship is required and must be the authenticated user.

linkReturns

A 201 Created response will be returned along with the new license object.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses", {
method: "POST",
headers: {
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
body: JSON.stringify({
"data": {
"type": "licenses",
"relationships": {
"policy": {
"data": { "type": "policies", "id": "37b632f4-8e1e-4af9-8717-634765364628" }
},
"user": {
"data": { "type": "users", "id": "015a33dd-3aca-43a9-8786-328042cce30a" }
}
}
}
})
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.post(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses",
headers={
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
data=json.dumps({
"data": {
"type": "licenses",
"relationships": {
"policy": {
"data": { "type": "policies", "id": "37b632f4-8e1e-4af9-8717-634765364628" }
},
"user": {
"data": { "type": "users", "id": "015a33dd-3aca-43a9-8786-328042cce30a" }
}
}
}
})
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses",
method: .post,
headers: [
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
],
parameters: [
"data": [
"type": "licenses",
"relationships": [
"policy": [
"data": [ "type": "policies", "id": "37b632f4-8e1e-4af9-8717-634765364628" ]
],
"user": [
"data": [ "type": "users", "id": "015a33dd-3aca-43a9-8786-328042cce30a" ]
]
]
]
],
encoding: JSONEncoding.default
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest("licenses", Method.POST);
 
request.AddHeader("Content-Type", "application/vnd.api+json");
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
request.AddJsonBody(new {
data = new {
type = "licenses",
relationships = new {
policy = new {
data = new { type = "policies", id = "37b632f4-8e1e-4af9-8717-634765364628" }
},
user = new {
data = new { type = "users", id = "015a33dd-3aca-43a9-8786-328042cce30a" }
}
}
}
});
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
import org.json.*
 
val body = JSONObject(mapOf(
"data" to mapOf(
"type" to "licenses",
"relationships" to mapOf(
"policy" to mapOf(
"data" to mapOf("type" to "policies", "id" to "37b632f4-8e1e-4af9-8717-634765364628")
),
"user" to mapOf(
"data" to mapOf("type" to "users", "id" to "015a33dd-3aca-43a9-8786-328042cce30a")
)
)
)
))
 
val res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses")
.header("Authorization", "Bearer {TOKEN}")
.header("Content-Type", "application/vnd.api+json")
.header("Accept", "application/vnd.api+json")
.body(body)
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
import org.json.*;
 
import static java.util.Map.ofEntries;
import static java.util.Map.entry;
 
JSONObject body = new JSONObject(ofEntries(
entry("data", ofEntries(
entry("type", "licenses"),
entry("relationships", ofEntries(
entry("policy", ofEntries(
entry("data", ofEntries(entry("type", "policies"), entry("id", "37b632f4-8e1e-4af9-8717-634765364628")))
)),
entry("user", ofEntries(
entry("data", ofEntries(entry("type", "users"), entry("id", "015a33dd-3aca-43a9-8786-328042cce30a")))
))
))
))
));
 
HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses")
.header("Authorization", "Bearer {TOKEN}")
.header("Content-Type", "application/vnd.api+json")
.header("Accept", "application/vnd.api+json")
.body(body)
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace web::json;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
value policy_;
policy_["type"] = value::string("policies");
policy_["id"] = value::string("37b632f4-8e1e-4af9-8717-634765364628");
 
value policy;
policy["data"] = policy_;
 
value user_;
user_["type"] = value::string("users");
user_["id"] = value::string("015a33dd-3aca-43a9-8786-328042cce30a");
 
value user;
user["data"] = user_;
 
value rels;
rels["policy"] = policy;
rels["user"] = user;
 
value data;
data["type"] = value::string("licenses");
data["relationships"] = rels;
 
value body;
body["data"] = data;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Content-Type", "application/vnd.api+json");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses");
req.set_method(methods::POST);
req.set_body(body.serialize());
 
client.request(req)
.then([](http_response res)
{
auto data = res.extract_json().get();
})
.wait();
curl -X POST https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}' \
-d '{
"data": {
"type": "licenses",
"relationships": {
"policy": {
"data": { "type": "policies", "id": "37b632f4-8e1e-4af9-8717-634765364628" }
},
"user": {
"data": { "type": "users", "id": "015a33dd-3aca-43a9-8786-328042cce30a" }
}
}
}
}'

Example response / 201 Created

{
"data": {
"id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2022-03-15T19:27:50.440Z",
"status": "ACTIVE",
"uses": 0,
"protected": false,
"suspended": false,
"scheme": null,
"encrypted": false,
"floating": true,
"concurrent": true,
"strict": false,
"maxMachines": 5,
"maxCores": 64,
"maxUses": null,
"requireCheckIn": false,
"lastValidated": null,
"lastCheckIn": null,
"nextCheckIn": null,
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "37b632f4-8e1e-4af9-8717-634765364628"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "015a33dd-3aca-43a9-8786-328042cce30a"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 4
}
},
"tokens": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements"
}
}
}
}
}

linkRetrieve a license

Retrieves the details of an existing license.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resource: either an admin, the product it belongs to, the license itself (via an activation token), or the user it belongs to.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

  • link:id

    string, required

    The identifier (UUID) or URL-safe key of the license to be retrieved. Cannot be a legacy encrypted license key.

linkReturns

A 200 OK response will be returned along with a license object.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/{ID}

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/eef41cf5-f32e-4dab-a867-b9738d87285b", {
method: "GET",
headers: {
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.get(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/eef41cf5-f32e-4dab-a867-b9738d87285b",
headers={
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/eef41cf5-f32e-4dab-a867-b9738d87285b",
headers: [
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
]
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"licenses/eef41cf5-f32e-4dab-a867-b9738d87285b",
Method.GET
);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.get("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/eef41cf5-f32e-4dab-a867-b9738d87285b")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.get("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/eef41cf5-f32e-4dab-a867-b9738d87285b")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses/eef41cf5-f32e-4dab-a867-b9738d87285b");
req.set_method(methods::GET);
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/eef41cf5-f32e-4dab-a867-b9738d87285b \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 200 OK

{
"data": {
"id": "eef41cf5-f32e-4dab-a867-b9738d87285b",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/eef41cf5-f32e-4dab-a867-b9738d87285b"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2022-03-15T19:27:50.440Z",
"status": "ACTIVE",
"uses": 0,
"protected": false,
"suspended": false,
"scheme": null,
"encrypted": false,
"floating": false,
"concurrent": true,
"strict": false,
"maxMachines": 5,
"maxCores": 64,
"maxUses": null,
"requireCheckIn": false,
"lastValidated": "2021-03-15T19:27:50.440Z",
"lastCheckIn": null,
"nextCheckIn": null,
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 0
}
},
"tokens": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens"
}
}
}
}
}

linkUpdate a license

Updates the specified license resource by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product it belongs to.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

  • link:id

    string, required

    The identifier (UUID) or URL-safe key of the license to be updated.

linkAttributes

  • linkdata.attributes.name

    string, optionalprotectedProtected attributes are only available for bearers with an admin or product role.

    The name of the license. This can be used to distinguish licenses from eachother.

  • linkdata.attributes.expiry

    timestamp (ISO8601 format), optionalprotectedProtected attributes are only available for bearers with an admin or product role.

    When the license will expire. Note: updating this attribute to an expiry in the past may not emit a license.expired webhook event.

  • linkdata.attributes.maxMachines

    integer, optionalprotectedProtected attributes are only available for bearers with an admin or product role.

    The maximum number of machines the license can have associated with it. This is by default inherited from the policy, but can be overriden on a per-license basis. Set to null to remove an override.

  • linkdata.attributes.maxCores

    integer, optionalprotectedProtected attributes are only available for bearers with an admin or product role.

    The maximum number of machine CPU cores the license can have associated with it. The count is the sum of all cores for the license's machines. This is by default inherited from the policy, but can be overriden on a per-license basis. Set to null to remove an override.

  • linkdata.attributes.maxUses

    integer, optionalprotectedProtected attributes are only available for bearers with an admin or product role.

    The maximum number of uses the license is allowed to have. This is by default inherited from the policy, but can be overriden on a per-license basis. Set to null to remove an override.

  • linkdata.attributes.protected

    boolean, optionalprotectedProtected attributes are only available for bearers with an admin or product role.

    Whether or not the license is protected. A protected license disallows users the ability to activate and manage machines themselves, useful in situations where you want to allow machine creation for a protected account or policy. If the license's policy is protected, they automatically inherit that value when left blank.

  • linkdata.attributes.suspended

    boolean, optionalprotectedProtected attributes are only available for bearers with an admin or product role.

    Whether or not the license is suspended. Note: updating this attribute directly will not emit a license.suspended webhook event.

  • linkdata.attributes.metadata

    object<string, scalar>, optionalprotectedProtected attributes are only available for bearers with an admin or product role.

    Object containing license metadata.

linkReturns

A 200 OK response will be returned along with the updated license object.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/{ID}

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827", {
method: "PATCH",
headers: {
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
body: JSON.stringify({
"data": {
"type": "licenses",
"attributes": {
"expiry": "2020-01-01T00:00:00.000Z"
}
}
})
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.patch(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827",
headers={
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
data=json.dumps({
"data": {
"type": "licenses",
"attributes": {
"expiry": "2020-01-01T00:00:00.000Z"
}
}
})
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827",
method: .patch,
headers: [
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
],
parameters: [
"data": [
"type": "licenses",
"attributes": [
"expiry": "2020-01-01T00:00:00.000Z"
]
]
],
encoding: JSONEncoding.default
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827",
Method.PATCH
);
 
request.AddHeader("Content-Type", "application/vnd.api+json");
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
request.AddJsonBody(new {
data = new {
type = "licenses",
attributes = new {
expiry = "2020-01-01T00:00:00.000Z"
}
}
});
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
import org.json.*
 
val body = JSONObject(mapOf(
"data" to mapOf(
"type" to "licenses",
"attributes" to mapOf(
"expiry" to "2020-01-01T00:00:00.000Z"
)
)
))
 
val res = Unirest.patch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827")
.header("Authorization", "Bearer {TOKEN}")
.header("Content-Type", "application/vnd.api+json")
.header("Accept", "application/vnd.api+json")
.body(body)
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
import org.json.*;
 
import static java.util.Map.ofEntries;
import static java.util.Map.entry;
 
JSONObject body = new JSONObject(ofEntries(
entry("data", ofEntries(
entry("type", "licenses"),
entry("attributes", ofEntries(
entry("expiry", "2020-01-01T00:00:00.000Z")
))
))
));
 
HttpResponse<JsonNode> res = Unirest.patch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827")
.header("Authorization", "Bearer {TOKEN}")
.header("Content-Type", "application/vnd.api+json")
.header("Accept", "application/vnd.api+json")
.body(body)
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace web::json;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
value attrs;
attrs["expiry"] = value::string("2020-01-01T00:00:00.000Z");
 
value data;
data["type"] = value::string("licenses");
data["attributes"] = attrs;
 
value body;
body["data"] = data;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Content-Type", "application/vnd.api+json");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827");
req.set_method(methods::PATCH);
req.set_body(body.serialize());
 
client.request(req)
.then([](http_response res)
{
auto data = res.extract_json().get();
})
.wait();
curl -X PATCH https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}' \
-d '{
"data": {
"type": "licenses",
"attributes": {
"expiry": "2020-01-01T00:00:00.000Z"
}
}
}'

Example response / 200 OK

{
"data": {
"id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2020-01-01T00:00:00.000Z",
"status": "ACTIVE",
"uses": 0,
"protected": false,
"suspended": false,
"scheme": null,
"encrypted": false,
"floating": false,
"concurrent": true,
"strict": false,
"maxMachines": 1,
"maxCores": 64,
"maxUses": null,
"requireCheckIn": false,
"lastValidated": "2021-03-15T19:27:50.440Z",
"lastCheckIn": null,
"nextCheckIn": null,
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 0
}
},
"tokens": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements"
}
}
}
}
}

linkDelete a license

Permanently deletes a license. It cannot be undone. This action also immediately deletes any machines that the license is associated with.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin, the product it belongs to, or if the license's policy is unprotected, the user it belongs to.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

  • link:id

    string, required

    The identifier (UUID) or URL-safe key of the license to be deleted.

linkReturns

A 204 No Content response will be returned.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/{ID}

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065", {
method: "DELETE",
headers: {
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
})
import requests
 
res = requests.delete(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
headers={
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
)
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
method: .delete,
headers: [
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
]
).responseJSON { response in
let status = response.response?.statusCode
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"licenses/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
Method.DELETE
);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.delete("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.delete("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065");
req.set_method(methods::DELETE);
 
client.request(req)
.then([](http_response res) {
auto status = res.status_code();
})
.wait();
curl -X DELETE https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065 \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 204 No Content

No content

linkList all licenses

Returns a list of licenses. The licenses are returned sorted by creation date, with the most recent licenses appearing first. Resources are automatically scoped to the authenticated bearer e.g. when authenticated as a user, only licenses of that specific user will be listed.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resources.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

linkFilters

  • linklimit

    integer, default is10

    A limit on the number of licenses to be returned. Limit must be a number between 1 and 100.

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?limit=25
  • linkpage

    object<string, integer>

    Object containing page size and page number. Page size must be a number between 1 and 100

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?page[size]=15&page[number]=2
  • linkstatus

    string

    The status of the license to filter by. One of: ACTIVE, INACTIVE, EXPIRING, EXPIRED, or SUSPENDED.

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?status=ACTIVE
  • linksuspended

    boolean

    The suspended status of the license to filter by.

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?suspended=true
  • linkexpiring

    boolean

    The expiring-soon status of the license to filter by. This will list all licenses expiring within the next 3 days.

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?expiring=true
  • linkexpired

    boolean

    The expiration status of the license to filter by. Please note that this is for filtering by the license's expiry only. We do not support filtering by license validity.

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?expired=true
  • linkunassigned

    boolean

    The user-relationship status of the license to filter by. A license without a user is considered unassigned.

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?unassigned=true
  • linkproduct

    string

    The identifier (UUID) of the product to filter by.

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?product=3ab38aae-bbf7-4846-9c32-af9d94bf5ad4
  • linkpolicy

    string

    The identifier (UUID) of the policy to filter by.

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?policy=0b4b1a9a-e25a-4f14-a95e-d9dd378d6065
  • linkuser

    string

    The identifier (UUID) or email of the user to filter by.

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?user=a5a154d2-f026-40fa-bc8d-a7e3ca415298
  • linkmachine

    string

    The identifier (UUID) of the machine to filter by.

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?machine=e4ab4f90-3203-48b3-bb33-a7377beb1d46
  • linkmetadata

    object<string, scalar>

    The metadata object to filter by.

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?metadata[customerId]=cust_af9d94bf5ad4

linkReturns

A 200 OK response will be returned along with a list of license objects.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses{FILTERS}

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?limit=15", {
method: "GET",
headers: {
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.get(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?limit=15",
headers={
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?limit=15",
headers: [
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
]
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest("licenses", Method.GET);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
request.AddParameter("limit", 15);
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.get("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.queryString("limit", 15)
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.get("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.queryString("limit", 15)
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Accept", "application/json");
 
uri_builder uri("/licenses");
uri.append_query("limit", 15);
 
req.set_request_uri(uri.to_uri());
req.set_method(methods::GET);
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses?limit=15 -g \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 200 OK

{
"data": [
{
"id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2022-03-15T19:27:50.440Z",
"status": "ACTIVE",
"uses": 0,
"protected": false,
"suspended": false,
"scheme": null,
"encrypted": false,
"floating": false,
"concurrent": true,
"strict": false,
"maxMachines": 1,
"maxCores": 64,
"maxUses": null,
"requireCheckIn": false,
"lastValidated": "2021-03-15T19:27:50.440Z",
"lastCheckIn": null,
"nextCheckIn": null,
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "37b632f4-8e1e-4af9-8717-634765364628"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "015a33dd-3aca-43a9-8786-328042cce30a"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 1
}
},
"tokens": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements"
}
}
}
},
]
}

linkLicense actions

Actions for the license resource.

linkQuick validate license

Action to quickly validate a license. This will check the following: if the license is suspended, if the license is expired, if the license is overdue for check-in, and if the license meets its machine requirements (if strict).

This endpoint does not allow scopes to be provided, and does not take required scopes into account during validation. If your policy requires any particular scopes to be specified, e.g. requireFingerprintScope, etc., you should use the POST version of this endpoint.

linkValidation Response Codes

Below are the possible values for the meta.constant key within the validation response. This can be used to better communicate failures to end-users and to handle specific failures within your application code.

Code Meaning
VALID The validated license resource or license key is valid.
OVERDUE The validated license is overdue for check-in.
SUSPENDED The validated license has been suspended.
EXPIRED The validated license is expired.
NO_MACHINE The validated license does not meet its node-locked policy's requirement of exactly 1 associated machine.
NO_MACHINES The validated license does not meet its floating policy's requirement of at least 1 associated machine.
TOO_MANY_MACHINES The validated license has exceeded its policy's machine limit.
TOO_MANY_CORES The validated license has exceeded its policy's machine core limit.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to validate the resource: either an admin, the product it belongs to, the license itself (via an activation token), or the user it belongs to.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

  • link:id

    string, required

    The identifier (UUID) or URL-safe key of the license to be validated. Cannot be a legacy encrypted license key.

linkReturns

A 200 OK response will be returned along with the validation result and the validated license object.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/{ID}/actions/validate

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate", {
method: "GET",
headers: {
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
})
 
const { meta, data, errors } = await response.json()
import requests
import json
 
res = requests.get(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate",
headers={
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate",
headers: [
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
]
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate",
Method.GET
);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.get("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.get("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate");
req.set_method(methods::GET);
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 200 OK

{
"meta": {
"ts": "2021-03-15T19:27:50.440Z",
"valid": true,
"detail": "is valid",
"constant": "VALID"
},
"data": {
"id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2020-01-01T00:00:00.000Z",
"status": "ACTIVE",
"uses": 0,
"protected": false,
"suspended": false,
"scheme": null,
"encrypted": false,
"floating": true,
"concurrent": true,
"strict": false,
"maxMachines": 5,
"maxCores": 64,
"maxUses": null,
"requireCheckIn": false,
"lastValidated": "2021-03-15T19:27:50.440Z",
"lastCheckIn": null,
"nextCheckIn": null,
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 0
}
},
"tokens": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements"
}
}
}
}
}

linkValidate license

Action to validate a license. This will check the following: if the license is suspended, if the license is expired, if the license is overdue for check-in, and if the license meets its machine requirements (if strict).

Additional scopes can also be applied, and may be required by the license's policy, e.g. a policy may set requireFingerprintScope=true, which will require that you specify a scope.fingerprint with the validation request in order to pass validation.

The scoping feature allows you to easily set up a node-locked or floating licensing model without additional logic on your end.

linkValidation Response Codes

Below are the possible values for the meta.constant key within the validation response. This can be used to better communicate failures to end-users and to handle specific failures within your application code.

Code Meaning
VALID The validated license resource or license key is valid.
SUSPENDED The validated license has been suspended.
EXPIRED The validated license is expired.
OVERDUE The validated license is overdue for check-in.
NO_MACHINE Not activated. The validated license does not meet its node-locked policy's requirement of exactly 1 associated machine.
NO_MACHINES Not activated. The validated license does not meet its floating policy's requirement of at least 1 associated machine.
TOO_MANY_MACHINES The validated license has exceeded its policy's machine limit.
TOO_MANY_CORES The validated license has exceeded its policy's machine core limit.
FINGERPRINT_SCOPE_REQUIRED The validated license requires a fingerprint scope to be provided during validation.
FINGERPRINT_SCOPE_MISMATCH Not activated. None of the validated license's machine relationships match the provided machine fingerprint scope.
FINGERPRINT_SCOPE_EMPTY A fingerprint scope was supplied but it has an empty or null value.
PRODUCT_SCOPE_REQUIRED The validated license requires a product scope to be provided during validation.
PRODUCT_SCOPE_MISMATCH The validated license's product relationship does not match the provided product scope.
POLICY_SCOPE_REQUIRED The validated license requires a policy scope to be provided during validation.
POLICY_SCOPE_MISMATCH The validated license's policy relationship does not match the provided policy scope.
MACHINE_SCOPE_REQUIRED The validated license requires a machine scope to be provided during validation.
MACHINE_SCOPE_MISMATCH None of the validated license's machine relationships match the provided machine scope.
ENTITLEMENTS_MISSING The validated license's entitlement relationship is missing one or more of the entitlement scope assertions.
ENTITLEMENTS_SCOPE_EMPTY An entitlements scope was supplied but it has an empty value.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to validate the resource: either an admin, the product it belongs to, the license itself (via an activation token), or the user it belongs to.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

  • link:id

    string, required

    The identifier (UUID) or URL-safe key of the license to be validated. Cannot be a legacy encrypted license key.

linkMeta

  • linkmeta.nonce

    integer, optional

    An arbitrary numerical nonce value that will be echoed back within the signed response body. This is useful for prevention of replay attacks.

  • linkmeta.scope

    object<string, string>, optional

    Scope to validate the license against i.e. if a license's key is associated with product X, but the validation request is scoped to product Y, it will fail validation because a matching license doesn't exist for that product.

  • linkmeta.scope.product

    string, optional

    The identifier (UUID) of the product to validate against. If the validated license is not associated with the given product, it is considered invalid.

  • linkmeta.scope.policy

    string, optional

    The identifier (UUID) of the policy to validate against. If the validated license is not associated with the given policy, it is considered invalid.

  • linkmeta.scope.fingerprints

    array<string>, optional

    An array of machine fingerprints to validate against. If the validated license's associated machines do not have fingerprints which match the provided fingerprints, according to the policy's fingerprint matching strategy, the license is considered invalid.

  • linkmeta.scope.fingerprint

    string, optional

    A single fingerprint of a machine to validate against. If the validated license's associated machines do not have a fingerprint which matches the provided fingerprint, the license is considered invalid.

  • linkmeta.scope.machine

    string, optional

    The identifier (UUID) of the machine to validate against. If the validated license's associated machines do not have an ID which matches the provided ID, the license is considered invalid.

  • linkmeta.scope.entitlements

    array<string>, optional

    An array of entitlement codes to validate against. If the validated license's entitlements do not have codes which match the provided entitlements, the license is considered invalid.

linkReturns

A 200 OK response will be returned along with the validation result and the validated license object.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/{ID}/actions/validate

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate", {
method: "POST",
headers: {
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
body: JSON.stringify({
"meta": {
"nonce": 1574265297,
"scope": {
"fingerprint": "9a:Eq:Uv:p3:yZ:tL:lC:Bz:mA:Eg:E6:Mk:YX:dK:NC"
}
}
})
})
 
const { meta, data, errors } = await response.json()
import requests
import json
 
res = requests.post(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate",
headers={
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
data=json.dumps({
"meta": {
"nonce": 1574265297,
"scope": {
"fingerprint": "9a:Eq:Uv:p3:yZ:tL:lC:Bz:mA:Eg:E6:Mk:YX:dK:NC"
}
}
})
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate",
method: .post,
headers: [
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
],
parameters: [
"meta": [
"nonce": 1574265297,
"scope": [
"fingerprint": "9a:Eq:Uv:p3:yZ:tL:lC:Bz:mA:Eg:E6:Mk:YX:dK:NC"
]
]
],
encoding: JSONEncoding.default
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate",
Method.POST
);
 
request.AddHeader("Content-Type", "application/vnd.api+json");
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
request.AddJsonBody(new {
meta = new {
nonce = 1574265297,
scope = new {
fingerprint = "9a:Eq:Uv:p3:yZ:tL:lC:Bz:mA:Eg:E6:Mk:YX:dK:NC"
}
}
});
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
import org.json.*
 
val body = JSONObject(mapOf(
"meta" to mapOf(
"nonce" to 1574265297,
"scope" to mapOf(
"fingerprint" to "9a:Eq:Uv:p3:yZ:tL:lC:Bz:mA:Eg:E6:Mk:YX:dK:NC"
)
)
))
 
val res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate")
.header("Authorization", "Bearer {TOKEN}")
.header("Content-Type", "application/vnd.api+json")
.header("Accept", "application/vnd.api+json")
.body(body)
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
import org.json.*;
 
import static java.util.Map.ofEntries;
import static java.util.Map.entry;
 
JSONObject body = new JSONObject(ofEntries(
entry("meta", ofEntries(
entry("nonce", 1574265297),
entry("scope", ofEntries(
entry("fingerprint", "9a:Eq:Uv:p3:yZ:tL:lC:Bz:mA:Eg:E6:Mk:YX:dK:NC")
))
))
));
 
HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate")
.header("Authorization", "Bearer {TOKEN}")
.header("Content-Type", "application/vnd.api+json")
.header("Accept", "application/vnd.api+json")
.body(body)
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace web::json;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
value scope;
scope["fingerprint"] = value::string("9a:Eq:Uv:p3:yZ:tL:lC:Bz:mA:Eg:E6:Mk:YX:dK:NC");
 
value meta;
meta["nonce"] = value::number(1574265297);
meta["scope"] = scope;
 
value body;
body["meta"] = meta;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Content-Type", "application/vnd.api+json");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate");
req.set_method(methods::POST);
req.set_body(body.serialize());
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl -X POST https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/validate \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}' \
-d '{
"meta": {
"nonce": 1574265297,
"scope": {
"fingerprint": "9a:Eq:Uv:p3:yZ:tL:lC:Bz:mA:Eg:E6:Mk:YX:dK:NC"
}
}
}'

Example response / 200 OK

{
"meta": {
"ts": "2021-03-15T19:27:50.440Z",
"valid": false,
"detail": "fingerprint scope does not match",
"constant": "FINGERPRINT_SCOPE_MISMATCH",
"nonce": 1574265297,
"scope": {
"fingerprint": "9a:Eq:Uv:p3:yZ:tL:lC:Bz:mA:Eg:E6:Mk:YX:dK:NC"
}
},
"data": {
"id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2022-03-15T19:27:50.440Z",
"status": "ACTIVE",
"uses": 0,
"protected": false,
"suspended": false,
"scheme": null,
"encrypted": false,
"floating": true,
"concurrent": true,
"strict": false,
"maxMachines": 5,
"maxCores": 64,
"maxUses": null,
"requireCheckIn": false,
"lastValidated": "2021-03-15T19:27:50.440Z",
"lastCheckIn": null,
"nextCheckIn": null,
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 0
}
},
"tokens": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements"
}
}
}
}
}

linkValidate key

Action to validate a license key. This will look up the license by its key and check the following: if the license is suspended, if the license is expired, if the license is overdue for check-in, and if the license meets its machine requirements (if strict).

Additional scopes can also be applied, and may be required by the license's policy, e.g. a policy may set requireFingerprintScope=true, which will require that you specify a scope.fingerprint with the validation request in order to pass validation.

The scoping feature allows you to easily set up a node-locked or floating licensing model without additional logic on your end.

linkValidation Response Codes

Below are the possible values for the meta.constant key within the validation response. This can be used to better communicate failures to end-users and to handle specific failures within your application code.

Code Meaning
VALID The validated license resource or license key is valid.
NOT_FOUND The validated license resource or license key does not exist.
SUSPENDED The validated license has been suspended.
EXPIRED The validated license is expired.
OVERDUE The validated license is overdue for check-in.
NO_MACHINE Not activated. The validated license does not meet its node-locked policy's requirement of exactly 1 associated machine.
NO_MACHINES Not activated. The validated license does not meet its floating policy's requirement of at least 1 associated machine.
TOO_MANY_MACHINES The validated license has exceeded its policy's machine limit.
TOO_MANY_CORES The validated license has exceeded its policy's machine core limit.
FINGERPRINT_SCOPE_REQUIRED The validated license requires a fingerprint scope to be provided during validation.
FINGERPRINT_SCOPE_MISMATCH Not activated. None of the validated license's machine relationships match the provided machine fingerprint scope.
FINGERPRINT_SCOPE_EMPTY A fingerprint scope was supplied but it has an empty or null value.
PRODUCT_SCOPE_REQUIRED The validated license requires a product scope to be provided during validation.
PRODUCT_SCOPE_MISMATCH The validated license's product relationship does not match the provided product scope.
POLICY_SCOPE_REQUIRED The validated license requires a policy scope to be provided during validation.
POLICY_SCOPE_MISMATCH The validated license's policy relationship does not match the provided policy scope.
MACHINE_SCOPE_REQUIRED The validated license requires a machine scope to be provided during validation.
MACHINE_SCOPE_MISMATCH None of the validated license's machine relationships match the provided machine scope.
ENTITLEMENTS_MISSING The validated license's entitlement relationship is missing one or more of the entitlement scope assertions.
ENTITLEMENTS_SCOPE_EMPTY An entitlements scope was supplied but it has an empty value.

linkAuthentication

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

linkMeta

  • linkmeta.key

    string, required

    The license key to validate.

  • linkmeta.nonce

    integer, optional

    An arbitrary numerical nonce value that will be echoed back within the signed response body. This is useful for prevention of replay attacks.

  • linkmeta.scope

    object<string, string>, optional

    Scope to validate the license against i.e. if a license's key is associated with product X, but the validation request is scoped to product Y, it will fail validation because a matching license doesn't exist for that product.

  • linkmeta.scope.product

    string, optional

    The identifier (UUID) of the product to validate against. If the validated license is not associated with the given product, it is considered invalid.

  • linkmeta.scope.policy

    string, optional

    The identifier (UUID) of the policy to validate against. If the validated license is not associated with the given policy, it is considered invalid.

  • linkmeta.scope.fingerprints

    array<string>, optional

    An array of machine fingerprints to validate against. If the validated license's associated machines do not have fingerprints which match the provided fingerprints, according to the policy's fingerprint matching strategy, the license is considered invalid.

  • linkmeta.scope.fingerprint

    string, optional

    A single fingerprint of a machine to validate against. If the validated license's associated machines do not have a fingerprint which matches the provided fingerprint, the license is considered invalid.

  • linkmeta.scope.machine

    string, optional

    The identifier (UUID) of the machine to validate against. If the validated license's associated machines do not have an ID which matches the provided ID, the license is considered invalid.

  • linkmeta.scope.entitlements

    array<string>, optional

    An array of entitlement codes to validate against. If the validated license's entitlements do not have codes which match the provided entitlements, the license is considered invalid.

linkReturns

A 200 OK response will be returned along with the validation result and the validated license object.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/actions/validate-key

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/actions/validate-key", {
method: "POST",
headers: {
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json"
},
body: JSON.stringify({
"meta": {
"key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
"scope": {
"fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC"
}
}
})
})
 
const { meta, data, errors } = await response.json()
import requests
import json
 
res = requests.post(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/actions/validate-key",
headers={
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json"
},
data=json.dumps({
"meta": {
"key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
"scope": {
"fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC"
}
}
})
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/actions/validate-key",
method: .post,
headers: [
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json"
],
parameters: [
"meta": [
"key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
"scope": [
"fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC"
]
]
],
encoding: JSONEncoding.default
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"licenses/actions/validate-key",
Method.POST
);
 
request.AddHeader("Content-Type", "application/vnd.api+json");
request.AddHeader("Accept", "application/vnd.api+json");
 
request.AddJsonBody(new {
meta = new {
key = "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
scope = new {
fingerprint = "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC"
}
}
});
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
import org.json.*
 
val body = JSONObject(mapOf(
"meta" to mapOf(
"key" to "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
"scope" to mapOf(
"fingerprint" to "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC"
)
)
))
 
val res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/actions/validate-key")
.header("Content-Type", "application/vnd.api+json")
.header("Accept", "application/vnd.api+json")
.body(body)
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
import org.json.*;
 
import static java.util.Map.ofEntries;
import static java.util.Map.entry;
 
JSONObject body = new JSONObject(ofEntries(
entry("meta", ofEntries(
entry("key", "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3"),
entry("scope", ofEntries(
entry("fingerprint", "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC")
))
))
));
 
HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/actions/validate-key")
.header("Content-Type", "application/vnd.api+json")
.header("Accept", "application/vnd.api+json")
.body(body)
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace web::json;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
value scope;
scope["fingerprint"] = value::string("4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC");
 
value meta;
meta["key"] = value::string("C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3");
meta["scope"] = scope;
 
value body;
body["meta"] = meta;
 
req.headers().add("Content-Type", "application/vnd.api+json");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses/actions/validate-key");
req.set_method(methods::POST);
req.set_body(body.serialize());
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl -X POST https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/actions/validate-key \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-d '{
"meta": {
"key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
"scope": {
"fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC"
}
}
}'

Example response / 200 OK

{
"meta": {
"ts": "2021-03-15T19:27:50.440Z",
"valid": false,
"detail": "is expired",
"constant": "EXPIRED",
"scope": {
"fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC"
}
},
"data": {
"id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2022-03-15T19:27:50.440Z",
"status": "ACTIVE",
"uses": 0,
"protected": false,
"suspended": false,
"scheme": null,
"encrypted": false,
"floating": true,
"concurrent": true,
"strict": false,
"maxMachines": 5,
"maxCores": 64,
"maxUses": null,
"requireCheckIn": false,
"lastValidated": "2021-03-15T19:27:50.440Z",
"lastCheckIn": null,
"nextCheckIn": null,
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 0
}
},
"tokens": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements"
}
}
}
}
}

linkSuspend license

Action to temporarily suspend (ban) a license. This will cause the license to fail validation until reinistated. To permanently revoke a license, see the revoke action.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to suspend the resource: either an admin or the product it belongs to.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

  • link:id

    string, required

    The identifier (UUID) or URL-safe key of the license to suspend. Cannot be a legacy encrypted license key.

linkReturns

A 200 OK response will be returned along with the suspended license object.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/{ID}/actions/suspend

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/suspend", {
method: "POST",
headers: {
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.post(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/suspend",
headers={
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/suspend",
method: .post,
headers: [
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
]
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/suspend",
Method.POST
);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/suspend")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/suspend")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/suspend");
req.set_method(methods::POST);
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl -X POST https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/suspend \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 200 OK

{
"data": {
"id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2020-01-01T00:00:00.000Z",
"status": "ACTIVE",
"uses": 0,
"protected": false,
"suspended": true,
"scheme": null,
"encrypted": false,
"floating": true,
"concurrent": true,
"strict": false,
"maxMachines": 5,
"maxCores": 64,
"maxUses": null,
"requireCheckIn": false,
"lastValidated": "2021-03-15T19:27:50.440Z",
"lastCheckIn": null,
"nextCheckIn": null,
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 0
}
},
"tokens": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements"
}
}
}
}
}

linkReinstate license

Action to reinstate a suspended license.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to reinstate the resource: either an admin or the product it belongs to.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

  • link:id

    string, required

    The identifier (UUID) or URL-safe key of the license to reinstate. Cannot be a legacy encrypted license key.

linkReturns

A 200 OK response will be returned along with the reinstated license object.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/{ID}/actions/reinstate

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reinstate", {
method: "POST",
headers: {
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.post(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reinstate",
headers={
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reinstate",
method: .post,
headers: [
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
]
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reinstate",
Method.POST
);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reinstate")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reinstate")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reinstate");
req.set_method(methods::POST);
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl -X POST https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reinstate \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 200 OK

{
"data": {
"id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2020-01-01T00:00:00.000Z",
"status": "ACTIVE",
"uses": 0,
"protected": false,
"suspended": false,
"scheme": null,
"encrypted": false,
"floating": true,
"concurrent": true,
"strict": false,
"maxMachines": 5,
"maxCores": 64,
"maxUses": null,
"requireCheckIn": false,
"lastValidated": "2021-03-15T19:27:50.440Z",
"lastCheckIn": null,
"nextCheckIn": null,
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 0
}
},
"tokens": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements"
}
}
}
}
}

linkRenew license

Action to renew a license. Extends license expiry by the policy's duration.

Renewals do not guarantee the license's renewed expiry will land on the same day as the original expiry. Renewals take the license's current expiry datetime and add, in seconds, the policy's duration. More complex logic for subscription purposes, such as ensuring the renewed expiry lands on the same day, you will need to calculate and update the expiry attribute yourself.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to renew the resource: either an admin, the product it belongs to, or if the license's policy is unprotected, the user it belongs to.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

  • link:id

    string, required

    The identifier (UUID) or URL-safe key of the license to renew. Cannot be a legacy encrypted license key.

linkReturns

A 200 OK response will be returned along with the renewed license object.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/{ID}/actions/renew

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/renew", {
method: "POST",
headers: {
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.post(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/renew",
headers={
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/renew",
method: .post,
headers: [
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
]
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/renew",
Method.POST
);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/renew")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/renew")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/renew");
req.set_method(methods::POST);
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl -X POST https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/renew \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 200 OK

{
"data": {
"id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2020-01-01T00:00:00.000Z",
"status": "ACTIVE",
"uses": 0,
"protected": false,
"suspended": false,
"scheme": null,
"encrypted": false,
"floating": false,
"concurrent": true,
"strict": false,
"maxMachines": 5,
"maxCores": 64,
"maxUses": null,
"requireCheckIn": false,
"lastValidated": "2021-03-15T19:27:50.440Z",
"lastCheckIn": null,
"nextCheckIn": null,
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 0
}
},
"tokens": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements"
}
}
}
}
}

linkRevoke license

Action to revoke (delete) a license. This cannot be undone. This action also immediately deletes any machines that the license is associated with.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to revoke the resource: either an admin, the product it belongs to, or if the license's policy is unprotected, the user it belongs to.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

  • link:id

    string, required

    The identifier (UUID) or URL-safe key of the license to revoke. Cannot be a legacy encrypted license key.

linkReturns

A 204 No Content response will be returned.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/{ID}/actions/revoke

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/revoke", {
method: "DELETE",
headers: {
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
})
import requests
import json
 
res = requests.delete(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/revoke",
headers={
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/revoke",
method: .delete,
headers: [
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
]
).responseJSON { response in
let status = response.response?.statusCode
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/revoke",
Method.DELETE
);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.delete("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/revoke")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.delete("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/revoke")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/revoke");
req.set_method(methods::DELETE);
 
client.request(req)
.then([](http_response res) {
auto status = res.status_code();
})
.wait();
curl -X DELETE https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/revoke \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 204 No Content

No content

linkCheck-In license

Action to check-in a license. Sets the license's lastCheckIn to the current time, and the license's nextCheckIn according to the policy's check-in interval.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to check-in the resource: either an admin, the product it belongs to, the license itself (via an activation token), or if the license's policy is unprotected, the user it belongs to.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

  • link:id

    string, required

    The identifier (UUID) or URL-safe key of the license to check-in. Cannot be a legacy encrypted license key.

linkReturns

A 200 OK response will be returned along with the checked in license object.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/{ID}/actions/check-in

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/check-in", {
method: "POST",
headers: {
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.post(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/check-in",
headers={
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/check-in",
method: .post,
headers: [
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
]
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/check-in",
Method.POST
);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/check-in")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/check-in")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/check-in");
req.set_method(methods::POST);
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl -X POST https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/check-in \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 200 OK

{
"data": {
"id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2020-01-01T00:00:00.000Z",
"status": "ACTIVE",
"uses": 0,
"protected": false,
"suspended": false,
"encrypted": false,
"floating": true,
"concurrent": true,
"strict": false,
"maxMachines": 5,
"maxCores": 64,
"maxUses": null,
"requireCheckIn": true,
"lastValidated": "2021-03-15T19:27:50.440Z",
"lastCheckIn": "2017-01-02T20:26:53.464Z",
"nextCheckIn": "2017-01-03T20:26:53.464Z",
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 0
}
},
"tokens": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements"
}
}
}
}
}

linkIncrement license usage

Action to increment a license's uses attribute in accordance with its policy's maxUses attribute. When the policy's maxUses limit is exceeded, the increment attempt will fail. When the policy's maxUses is set to null, there is no limit on usage.

The uses attribute cannot be incremented more than the maximum value of a 4 byte integer, 2,147,483,647. If you need to store larger values, you may need to store usage information in your own datastore. Please reach out if you have any questions.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to increment the resource's usage: either an admin, the product it belongs to, the license itself (via an activation token), or if the license's policy is unprotected, the user it belongs to.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

  • link:id

    string, required

    The identifier (UUID) or URL-safe key of the license to increment usage for. Cannot be a legacy encrypted license key.

linkMeta

  • linkmeta.increment

    integer, optional, default is1

    The amount to increment the license's usage by.

linkReturns

A 200 OK response will be returned along with the incremented uses count within the license object. A 422 Unprocessable Entity will be returned in the case where the policy's maxUses count has been exceeded.

Though rare, a 409 Conflict will be returned in the case where a previous increment operation has not yet completed. This is likely due to you firing off too many increment requests in parallel. Increase the time between requests or increment in larger batches by utilizing the meta.increment parameter.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/{ID}/actions/increment-usage

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/increment-usage", {
method: "POST",
headers: {
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
body: JSON.stringify({
"meta": {
"increment": 25
}
})
})
 
const { meta, data, errors } = await response.json()
import requests
import json
 
res = requests.post(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/increment-usage",
headers={
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
data=json.dumps({
"meta": {
"increment": 25
}
})
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/increment-usage",
method: .post,
headers: [
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
],
parameters: [
"meta": [
"increment": 25
]
],
encoding: JSONEncoding.default
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/increment-usage",
Method.POST
);
 
request.AddHeader("Content-Type", "application/vnd.api+json");
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
request.AddJsonBody(new {
meta = new {
increment = 25
}
});
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
import org.json.*
 
val body = JSONObject(mapOf(
"meta" to mapOf(
"increment" to 25
)
))
 
val res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/increment-usage")
.header("Authorization", "Bearer {TOKEN}")
.header("Content-Type", "application/vnd.api+json")
.header("Accept", "application/vnd.api+json")
.body(body)
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
import org.json.*;
 
import static java.util.Map.ofEntries;
import static java.util.Map.entry;
 
JSONObject body = new JSONObject(ofEntries(
entry("meta", ofEntries(
entry("increment", 25)
))
));
 
HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/increment-usage")
.header("Authorization", "Bearer {TOKEN}")
.header("Content-Type", "application/vnd.api+json")
.header("Accept", "application/vnd.api+json")
.body(body)
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace web::json;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
value meta;
meta["increment"] = value::int(25);
 
value body;
body["meta"] = meta;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Content-Type", "application/vnd.api+json");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/increment-usage");
req.set_method(methods::POST);
req.set_body(body.serialize());
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl -X POST https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/increment-usage \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}' \
-d '{
"meta": {
"increment": 25
}
}'

Example response / 200 OK

{
"data": {
"id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2020-01-01T00:00:00.000Z",
"status": "ACTIVE",
"uses": 25,
"protected": false,
"suspended": false,
"scheme": null,
"encrypted": false,
"floating": true,
"concurrent": true,
"strict": false,
"maxMachines": 5,
"maxCores": 64,
"maxUses": 100,
"requireCheckIn": true,
"lastValidated": "2021-03-15T19:27:50.440Z",
"lastCheckIn": "2017-01-02T20:26:53.464Z",
"nextCheckIn": "2017-01-03T20:26:53.464Z",
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 0
}
},
"tokens": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements"
}
}
}
}
}

linkDecrement license usage

Action to decrement a license's uses attribute in accordance with its policy's maxUses attribute.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to decrement the resource's usage: either an admin or the product it belongs to.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

  • link:id

    string, required

    The identifier (UUID) or URL-safe key of the license to decrement usage for. Cannot be a legacy encrypted license key.

linkMeta

  • linkmeta.decrement

    integer, optional, default is1

    The amount to decrement the license's usage by.

linkReturns

A 200 OK response will be returned along with the decremented uses count within the license object.

Though rare, a 409 Conflict will be returned in the case where a previous decrement operation has not yet completed. This is likely due to you firing off too many decrement requests in parallel. Increase the time between requests or decrement in larger batches by utilizing the meta.decrement parameter.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/{ID}/actions/decrement-usage

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/decrement-usage", {
method: "POST",
headers: {
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.post(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/decrement-usage",
headers={
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/decrement-usage",
method: .post,
headers: [
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
]
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/decrement-usage",
Method.POST
);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/decrement-usage")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/decrement-usage")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/decrement-usage");
req.set_method(methods::POST);
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl -X POST https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/decrement-usage \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 200 OK

{
"data": {
"id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2020-01-01T00:00:00.000Z",
"status": "ACTIVE",
"uses": 0,
"protected": false,
"suspended": false,
"scheme": null,
"encrypted": false,
"floating": true,
"concurrent": true,
"strict": false,
"maxMachines": 5,
"maxCores": 64,
"maxUses": 5,
"requireCheckIn": true,
"lastValidated": "2021-03-15T19:27:50.440Z",
"lastCheckIn": "2017-01-02T20:26:53.464Z",
"nextCheckIn": "2017-01-03T20:26:53.464Z",
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 0
}
},
"tokens": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements"
}
}
}
}
}

linkReset license usage

Action to reset a license's uses attribute to 0.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to reset the resource's usage: either an admin or the product it belongs to.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

  • link:id

    string, required

    The identifier (UUID) or URL-safe key of the license to reset usage for. Cannot be a legacy encrypted license key.

linkReturns

A 200 OK response will be returned along with the reset uses count within the license object.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/{ID}/actions/reset-usage

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reset-usage", {
method: "POST",
headers: {
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.post(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reset-usage",
headers={
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reset-usage",
method: .post,
headers: [
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
]
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reset-usage",
Method.POST
);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reset-usage")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reset-usage")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reset-usage");
req.set_method(methods::POST);
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl -X POST https://api.keygen.sh/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/actions/reset-usage \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 200 OK

{
"data": {
"id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827",
"type": "licenses",
"links": {
"self": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
},
"attributes": {
"name": null,
"key": "6DFB15-6597FC-B7DBB6-E34DAB-9D77C0-V3",
"expiry": "2020-01-01T00:00:00.000Z",
"status": "ACTIVE",
"uses": 0,
"protected": false,
"suspended": false,
"scheme": null,
"encrypted": false,
"floating": true,
"concurrent": true,
"strict": false,
"maxMachines": 5,
"maxCores": 64,
"maxUses": 5,
"requireCheckIn": true,
"lastValidated": "2021-03-15T19:27:50.440Z",
"lastCheckIn": "2017-01-02T20:26:53.464Z",
"nextCheckIn": "2017-01-03T20:26:53.464Z",
"metadata": {},
"created": "2017-01-02T20:26:53.464Z",
"updated": "2017-01-02T20:26:53.464Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/product"
},
"data": {
"type": "products",
"id": "eb4e14a7-ea41-4ede-b3fe-5e835c17156b"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy"
},
"data": {
"type": "policies",
"id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
}
},
"user": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user"
},
"data": {
"type": "users",
"id": "e8bf27c0-5f9c-4135-a65c-f52706c5fd4c"
}
},
"machines": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/machines"
},
"meta": {
"count": 0
}
},
"tokens": {
"links": {
"related"<