Select programming language for code examples

linkPolicies

linkThe policy object

Below you will find the various attributes for the policy resource, as well as the policy resource's relationships. Your policies define the different types of licenses that a given product offers. For example, you may offer yearly licenses, as well as shorter time-limited free trial licenses that lack certain entitlements.

Another example would be configuring a yearly software license that once expired, still functions normally, but is disallowed release upgrades after expiration. This is something you can accomplish using policies.

linkAttributes

  • linkdata.attributes.name

    string

    The name of the policy.

  • linkdata.attributes.duration

    integer

    The duration for the policy in seconds. When a new license implements the policy, the license's expiry is calculated with this value (i.e. time.now + policy.duration). If null, licenses will never expire.

  • linkdata.attributes.strict

    boolean, default isfalse

    When enabled, a license that implements the policy will be considered invalid if its machine or machine core limit is surpassed. In addition, strict requires a license to have at least 1 machine associated with it in order to pass validation.

  • linkdata.attributes.floating

    boolean, default isfalse

    When enabled, a license that implements the policy will be valid across multiple machines. Though this is not enforced i.e. it does not invalidate a license if it's associated with more than 1 machine unless the policy is strict.

  • linkdata.attributes.concurrent

    boolean, default istrue

    Whether or not to allow the activation of additional machines after a given license has reached its max machine limit, i.e. machine overages. This allows a "concurrent" licensing model, where you allow a set number of machines to be activated at one time, and exceeding that limit may invalidate all current sessions. When this is disabled and a user attempts to exceed the policy's machine limit, an error response will be returned. For example, when enabled, a license with a machine limit of 3 may exceed that limit by adding 4 or more machines, though the license may then become invalid if the policy is also "strict."

  • linkdata.attributes.scheme

    string

    The cryptographic encryption/signature scheme used on license keys. Can be used to implement offline licensing by storing tamper-proof data within a license's key. When null or omitted, the license's key will be stored unchanged.

    Even though we're signing or encrypting license keys, that doesn't mean the key you specify is hidden. Keep in mind that the contents of the keys are usually base64url encoded (using RFC 4648, a URL-safe version of base64 which is supported in most programming languages), meaning they are publicly readable if decoded. For more info, see the signature section. Do not store sensitive information within keys, as the contents can be read by decoding the key.

    Options

    • ED25519_SIGN: Sign license keys with your account's Ed25519 signing key, using elliptic curve cryptography and SHA512. The given license key data will be base64url encoded and then prefixed with key/ before signing, and the signing data's signature will be base64url encoded and then appended onto the end of the signing data, delimited by the . character, e.g. key/{URLBASE64_KEY}.{URLBASE64_SIGNATURE}. This is our recommended signing scheme, but it may not be supported in your preferred programming language.
    • RSA_2048_PKCS1_PSS_SIGN_V2: Sign license keys with your account's 2048-bit RSA private key using RSA PKCS1-PSS padding, with a SHA256 digest, max salt length, and a SHA256 MGF1. The provided embedded dataset will be base64url encoded and then prefixed with key/ before signing, and the signing data's signature will be base64url encoded and then appended onto the end of the signing data, delimited by the . character, e.g. key/{URLBASE64_KEY}.{URLBASE64_SIGNATURE}, resulting in the final key. This is our recommended RSA scheme, but it may not be supported in your preferred programming language.
    • RSA_2048_PKCS1_SIGN_V2: Sign license keys with your account's 2048-bit RSA private key using RSA PKCS1 v1.5 padding, with a SHA256 digest. The provided embedded dataset will be base64url encoded and then prefixed with key/ before signing, and the signing data's signature will be base64url encoded and then appended onto the end of the signing data, delimited by the . character, e.g. key/{URLBASE64_KEY}.{URLBASE64_SIGNATURE}, resulting in the final key.
    • RSA_2048_PKCS1_ENCRYPT: Encrypt license keys with your account's 2048-bit RSA private key using RSA PKCS1 v1.5 padding. The provided dataset will be encrypted using your account's private key and then base64url encoded, resulting in the final key. The key can be decrypted using your account's public key. The key must contain no more than 245 bytes (please note this is byte length not string length).
    • RSA_2048_JWT_RS256: Encode a license claims payload into a JWT using the RS256 algorithm. The license key must be a valid JWT claims payload (i.e. a JSON encoded string). The JWT will be signed using your account's 2048-bit RSA private key and can be verified using your account's public key. The resulting key will be a full JSON Web Token. We do not modify your claims payload.
    • RSA_2048_PKCS1_PSS_SIGN: Deprecated: use v2. Sign license keys with your account's 2048-bit RSA private key using RSA PKCS1-PSS padding, with a SHA256 digest, max salt length, and a SHA256 MGF1. The provided embedded dataset will be base64url encoded, and its signature will be base64url encoded and then appended onto the end of the encoded key, delimited by the . character, e.g. {URLBASE64_KEY}.{URLBASE64_SIGNATURE}, resulting in the final key.
    • RSA_2048_PKCS1_SIGN: Deprecated: use v2. Sign license keys with your account's 2048-bit RSA private key using RSA PKCS1 v1.5 padding, with a SHA256 digest. The provided embedded dataset will be base64url encoded, and its signature will be base64url encoded and then appended onto the end of the encoded key, delimited by the . character, e.g. {URLBASE64_KEY}.{URLBASE64_SIGNATURE}, resulting in the final key.
  • linkdata.attributes.requireProductScope

    boolean, default isfalse

    When enabled, validating a license that implements the policy will require a product scope that matches the licenses's product relationship by its identifier (UUID).

  • linkdata.attributes.requirePolicyScope

    boolean, default isfalse

    When enabled, validating a license that implements the policy will require a policy scope that matches the licenses's policy relationship by its identifier (UUID).

  • linkdata.attributes.requireMachineScope

    boolean, default isfalse

    When enabled, validating a license that implements the policy will require a machine scope that matches at least 1 of the licenses's machine relationships by its identifier (UUID).

  • linkdata.attributes.requireFingerprintScope

    boolean, default isfalse

    When enabled, validating a license that implements the policy will require a fingerprint scope that matches at least 1 of the licenses's machine relationships by its fingerprint.

  • linkdata.attributes.requireCheckIn

    boolean, default isfalse

    When enabled, a license that implements the policy 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.

  • linkdata.attributes.checkInInterval

    string

    One of day, week, month or year. The frequency at which a license should check-in.

    Options

    • day: Require a license implementing the policy to check-in at least once every day to remain valid.
    • week: Require a license implementing the policy to check-in at least once every week to remain valid.
    • month: Require a license implementing the policy to check-in at least once every month to remain valid.
    • year: Require a license implementing the policy to check-in at least once every year to remain valid.
  • linkdata.attributes.checkInIntervalCount

    integer

    The number of intervals (specified in the check-in interval property) between each required check-in. For example, checkInInterval=week and checkInIntervalCount=2 requires check-in every 2 weeks. Must be a number between 1 and 365 inclusive.

  • linkdata.attributes.usePool

    boolean, default isfalse

    Whether or not to pull license keys from a finite pool of pre-determined keys. This is useful for invite-only programs such as a private beta, when you need a limited set of licenses, or when you want to define the keys manually. This cannot be changed later on.

  • linkdata.attributes.maxMachines

    integer

    The maximum number of machines a license implementing the policy can have associated with it. This is only enforced when the policy is strict. When null, an unlimited number of machines may be associated with a license if the policy is floating. Must be a number greater than 0, and must be equal to 1 for non-floating policies.

  • linkdata.attributes.maxCores

    integer

    The maximum number of machine CPU cores a license implementing the policy can have associated with it. The count is the sum of all cores for the license's machines. This is inherited from the policy. When null, a license which implements the policy can have an unlimited number of CPU cores.

  • linkdata.attributes.maxUses

    integer

    The maximum number of uses a license implementing the policy can have. Cannot exceed 2,147,483,647, which is the maximum value of a 4 byte integer. When null, a license which implements the policy can have an unlimited number of uses. This attribute is not taken into account during license validation. See the license's usage-related actions for more details.

  • linkdata.attributes.encrypted

    boolean, default isfalsedeprecatedThis attribute has been deprecated and its use is no longer recommended.

    This field has been deprecated and should no longer be used. It previously encrypted license keys at-rest, but this is now the default for all resources stored within our databases.

  • linkdata.attributes.protected

    boolean, default isinherited

    Whether or not the policy is protected. A protected policy disallows users the ability to create and manage licenses themselves, useful in situations where Keygen is only managed server-side or when you aren't listening for the appropriate user-initiated webhook events. If the account is protected, all policies automatically inherit that value when left blank.

  • linkdata.attributes.heartbeatDuration

    integer

    The custom heartbeat duration for the policy, in seconds. When a machine has an active heartbeat monitor, the machine must send a heartbeat ping within this timeframe to remain activated.

  • linkdata.attributes.fingerprintUniquenessStrategy

    string, default isUNIQUE_PER_LICENSE

    The uniqueness validation strategy for machine fingerprints. You can utilize this to prevent duplicate fingerprints across a variety of scopes.

    This is especially useful for disallowing trial licenses for a specific machine (i.e. device) that had previously completed a trial evaluation using another trial license.

    Options

    • UNIQUE_PER_ACCOUNT: Machine fingerprints must be unique across the entire Keygen account.
    • UNIQUE_PER_PRODUCT: Machine fingerprints must be unique across all licenses belonging to the policy's product.
    • UNIQUE_PER_POLICY: Machine fingerprints must be unique across all licenses for the policy.
    • UNIQUE_PER_LICENSE: Machine fingerprints must be unique to the license.
  • linkdata.attributes.fingerprintMatchingStrategy

    string, default isMATCH_ANY

    The matching strategy for machine fingerprints supplied during a license validation.

    This is especially useful for activating indivdual components of a given device, e.g. HDD ID, mobo ID, MAC addresses, IP addresses, etc., and then requiring that some, most, or all components match during a license validation.

    Options

    • MATCH_ANY: At least 1 of the supplied machine fingerprints must match a fingerprint for the license's associated machines. E.g. if 3 fingerprints are supplied, at least 1 of them must match.
    • MATCH_MOST: The majority of supplied machine fingerprints must match the fingerprints for the license's associated machines. E.g. if 3 fingerprints are supplied, at least 2 of them must match.
    • MATCH_ALL: All supplied machine fingerprints must match the fingerprints for the license's associated machines. E.g. if 3 fingerprints are supplied, all 3 of them must match.
  • linkdata.attributes.expirationStrategy

    string, default isRESTRICT_ACCESS

    The strategy for expired licenses during a license validation and when accessing releases.

    This is useful in scenarios where you want to allow normal product usage for expired licenses, as well as access to older releases published prior their expiry, but restrict access to newer releases published after the expiry.

    Options

    • RESTRICT_ACCESS: Expired licenses can continue to access releases published prior to their expiry, but automatic upgrades are disabled. Validation scopes take precedence over expiry check during license validation.
    • REVOKE_ACCESS: Expired licenses are no longer able to access any releases, including past releases and upgrades. Expiry check takes precedence over scopes during license validation.
  • linkdata.attributes.metadata

    object<string, scalar>

    Object containing policy metadata.

  • linkdata.attributes.created

    timestamp (ISO8601 format)read only

    When the policy was created.

  • linkdata.attributes.updated

    timestamp (ISO8601 format)read only

    When the policy was last updated.

linkRelationships

  • linkdata.relationships.account

    individual

    The account that the policy belongs to.

  • linkdata.relationships.product

    individual

    The product that the policy is associated with.

  • linkdata.relationships.pool

    collection

    The pool of pre-determined keys for the policy.

  • linkdata.relationships.licenses

    collection

    The licenses that implement the policy.

Example object

{
"data": {
"id": "0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
"type": "policies",
"links": {
"self": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065"
},
"attributes": {
"name": "Premium Add-On",
"duration": 1209600,
"strict": false,
"floating": true,
"concurrent": true,
"scheme": null,
"requireProductScope": false,
"requirePolicyScope": false,
"requireMachineScope": false,
"requireFingerprintScope": false,
"requireCheckIn": false,
"checkInInterval": null,
"checkInIntervalCount": null,
"usePool": false,
"maxMachines": 5,
"maxCores": null,
"maxUses": null,
"encrypted": false,
"protected": false,
"heartbeatDuration": null,
"fingerprintUniquenessStrategy": "UNIQUE_PER_LICENSE",
"fingerprintMatchingStrategy": "MATCH_ANY",
"expirationStrategy": "RESTRICT_ACCESS",
"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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/product"
},
"data": {
"type": "products",
"id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4"
}
},
"pool": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/pool"
}
},
"licenses": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/licenses"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements"
}
}
}
}
}

linkCreate a policy

Creates a new policy resource.

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.

linkAttributes

  • linkdata.attributes.name

    string, required

    The name of the policy.

  • linkdata.attributes.duration

    integer, optional

    The duration for the policy in seconds. When a new license implements the policy, the license's expiry is calculated with this value (i.e. time.now + policy.duration). If null, licenses will never expire.

  • linkdata.attributes.scheme

    string, optional

    The cryptographic encryption/signature scheme used on license keys. Can be used to implement offline licensing by storing tamper-proof data within a license's key. When null or omitted, the license's key will be stored unchanged.

    Even though we're signing or encrypting license keys, that doesn't mean the key you specify is hidden. Keep in mind that the contents of the keys are usually base64url encoded (using RFC 4648, a URL-safe version of base64 which is supported in most programming languages), meaning they are publicly readable if decoded. For more info, see the signature section. Do not store sensitive information within keys, as the contents can be read by decoding the key.

    Options

    • ED25519_SIGN: Sign license keys with your account's Ed25519 signing key, using elliptic curve cryptography and SHA512. The given license key data will be base64url encoded and then prefixed with key/ before signing, and the signing data's signature will be base64url encoded and then appended onto the end of the signing data, delimited by the . character, e.g. key/{URLBASE64_KEY}.{URLBASE64_SIGNATURE}. This is our recommended signing scheme, but it may not be supported in your preferred programming language. Signatures are deterministic.
    • RSA_2048_PKCS1_PSS_SIGN_V2: Sign license keys with your account's 2048-bit RSA private key using RSA PKCS1-PSS padding, with a SHA256 digest, max salt length, and a SHA256 MGF1. The provided embedded dataset will be base64url encoded and then prefixed with key/ before signing, and the signing data's signature will be base64url encoded and then appended onto the end of the signing data, delimited by the . character, e.g. key/{URLBASE64_KEY}.{URLBASE64_SIGNATURE}, resulting in the final key. This is our recommended RSA scheme, but it may not be supported in your preferred programming language. Signatures are non-deterministic.
    • RSA_2048_PKCS1_SIGN_V2: Sign license keys with your account's 2048-bit RSA private key using RSA PKCS1 v1.5 padding, with a SHA256 digest. The provided embedded dataset will be base64url encoded and then prefixed with key/ before signing, and the signing data's signature will be base64url encoded and then appended onto the end of the signing data, delimited by the . character, e.g. key/{URLBASE64_KEY}.{URLBASE64_SIGNATURE}, resulting in the final key. Signatures are deterministic.
    • RSA_2048_PKCS1_ENCRYPT: Encrypt license keys with your account's 2048-bit RSA private key using RSA PKCS1 v1.5 padding. The provided dataset will be encrypted using your account's private key and then base64url encoded, resulting in the final key. The key can be decrypted using your account's public key. The key must contain no more than 245 bytes (please note this is byte length not string length).
    • RSA_2048_JWT_RS256: Encode a license claims payload into a JWT using the RS256 algorithm. The license key must be a valid JWT claims payload (i.e. a JSON encoded string). The JWT will be signed using your account's 2048-bit RSA private key and can be verified using your account's public key. The resulting key will be a full JSON Web Token. We do not modify your claims payload.
    • RSA_2048_PKCS1_PSS_SIGN: Deprecated: use v2. Sign license keys with your account's 2048-bit RSA private key using RSA PKCS1-PSS padding, with a SHA256 digest, max salt length, and a SHA256 MGF1. The provided embedded dataset will be base64url encoded, and its signature will be base64url encoded and then appended onto the end of the encoded key, delimited by the . character, e.g. {URLBASE64_KEY}.{URLBASE64_SIGNATURE}, resulting in the final key.
    • RSA_2048_PKCS1_SIGN: Deprecated: use v2. Sign license keys with your account's 2048-bit RSA private key using RSA PKCS1 v1.5 padding, with a SHA256 digest. The provided embedded dataset will be base64url encoded, and its signature will be base64url encoded and then appended onto the end of the encoded key, delimited by the . character, e.g. {URLBASE64_KEY}.{URLBASE64_SIGNATURE}, resulting in the final key.
  • linkdata.attributes.strict

    boolean, optional

    When enabled, a license that implements the policy will be considered invalid if its machine or machine core limit is surpassed. In addition, strict requires a license to have at least 1 machine associated with it in order to pass validation.

  • linkdata.attributes.floating

    boolean, optional

    When enabled, a license that implements the policy will be valid across multiple machines. Though this is not enforced i.e. it does not invalidate a license if it's associated with more than 1 machine unless the policy is strict.

  • linkdata.attributes.concurrent

    boolean, optional

    Whether or not to allow the activation of additional machines after a given license has reached its max machine limit, i.e. machine overages. This allows a "concurrent" licensing model, where you allow a set number of machines to be activated at one time, and exceeding that limit may invalidate all current sessions. When this is disabled and a user attempts to exceed the policy's machine limit, an error response will be returned. For example, when enabled, a license with a machine limit of 3 may exceed that limit by adding 4 or more machines, though the license may then become invalid if the policy is also strict.

  • linkdata.attributes.requireProductScope

    boolean, optional

    When enabled, validating a license that implements the policy will require a product scope that matches the licenses's product relationship by its identifier (UUID).

  • linkdata.attributes.requirePolicyScope

    boolean, optional

    When enabled, validating a license that implements the policy will require a policy scope that matches the licenses's policy relationship by its identifier (UUID).

  • linkdata.attributes.requireMachineScope

    boolean, optional

    When enabled, validating a license that implements the policy will require a machine scope that matches at least 1 of the licenses's machine relationships by its identifier (UUID).

  • linkdata.attributes.requireFingerprintScope

    boolean, optional

    When enabled, validating a license that implements the policy will require a fingerprint scope that matches at least 1 of the licenses's machine relationships by its fingerprint.

  • linkdata.attributes.requireCheckIn

    boolean, optional

    When enabled, a license that implements the policy 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.

  • linkdata.attributes.checkInInterval

    string, optional

    One of day, week, month or year. The frequency at which a license should check-in.

    Options

    • day: Require a license implementing the policy to check-in at least once every day to remain valid.
    • week: Require a license implementing the policy to check-in at least once every week to remain valid.
    • month: Require a license implementing the policy to check-in at least once every month to remain valid.
    • year: Require a license implementing the policy to check-in at least once every year to remain valid.
  • linkdata.attributes.checkInIntervalCount

    integer, optional

    The number of intervals (specified in the check-in interval property) between each required check-in. For example, checkInInterval=week and checkInIntervalCount=2 requires check-in every 2 weeks. Must be a number between 1 and 365 inclusive.

  • linkdata.attributes.usePool

    boolean, optional

    Whether or not to pull license keys from a finite pool of pre-determined keys. This is useful for invite-only programs such as a private beta, when you need a limited set of licenses, or when you want to define the keys manually. This cannot be changed later on.

  • linkdata.attributes.maxMachines

    integer, optional

    The maximum number of machines a license implementing the policy can have associated with it. This is only enforced when the policy is strict. When null, an unlimited number of machines may be associated with a license if the policy is floating. Must be a number greater than 0, and must be equal to 1 for non-floating policies.

  • linkdata.attributes.maxCores

    integer, optional

    The maximum number of machine CPU cores a license implementing the policy can have associated with it. The count is the sum of all cores for the license's machines. This is inherited from the policy. When null, a license which implements the policy can have an unlimited number of CPU cores.

  • linkdata.attributes.maxUses

    integer, optional

    The maximum number of uses a license implementing the policy can have. Cannot exceed 2,147,483,647, which is the maximum value of a 4 byte integer. When null, a license which implements the policy can have an unlimited number of uses. This attribute is not taken into account during license validation. See the license's usage-related actions for more details.

  • linkdata.attributes.protected

    boolean, optional

    Whether or not the policy is protected. A protected policy disallows users the ability to create and manage licenses themselves, useful in situations where Keygen is only managed server-side or when you aren't listening for the appropriate user-initiated webhook events. If the account is protected, all policies automatically inherit that value when left blank.

  • linkdata.attributes.heartbeatDuration

    integer, optional

    The custom heartbeat duration for the policy, in seconds. When a machine has an active heartbeat monitor, the machine must send a heartbeat ping within this timeframe to remain activated.

  • linkdata.attributes.fingerprintUniquenessStrategy

    string, optional

    The uniqueness validation strategy for machine fingerprints. You can utilize this to prevent duplicate fingerprints across a variety of scopes.

    This is especially useful for disallowing trial licenses for a specific machine (i.e. device) that had previously completed a trial evaluation using another trial license.

    Options

    • UNIQUE_PER_ACCOUNT: Machine fingerprints must be unique across the entire Keygen account.
    • UNIQUE_PER_PRODUCT: Machine fingerprints must be unique across all licenses belonging to the policy's product.
    • UNIQUE_PER_POLICY: Machine fingerprints must be unique across all licenses for the policy.
    • UNIQUE_PER_LICENSE: Machine fingerprints must be unique to the license.
  • linkdata.attributes.fingerprintMatchingStrategy

    string, optional

    The matching strategy for machine fingerprints supplied during a license validation.

    Options

    • MATCH_ANY: At least 1 of the supplied machine fingerprints must match a fingerprint for the license's associated machines. E.g. if 3 fingerprints are supplied, at least 1 of them must match.
    • MATCH_MOST: The majority of supplied machine fingerprints must match the fingerprints for the license's associated machines. E.g. if 3 fingerprints are supplied, at least 2 of them must match.
    • MATCH_ALL: All supplied machine fingerprints must match the fingerprints for the license's associated machines. E.g. if 3 fingerprints are supplied, all 3 of them must match.
  • linkdata.attributes.expirationStrategy

    string, optional

    The strategy for expired licenses during a license validation and when accessing releases.

    Options

    • RESTRICT_ACCESS: Expired licenses can continue to access releases published prior to their expiry, but automatic upgrades are disabled. Validation scopes take precedence over expiry check during license validation.
    • REVOKE_ACCESS: Expired licenses are no longer able to access any releases, including past releases and upgrades. Expiry check takes precedence over scopes during license validation.
  • linkdata.attributes.metadata

    object<string, scalar>, optional

    Object containing policy metadata.

linkRelationships

linkReturns

A 201 Created response will be returned along with the new policy 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}/policies

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies", {
method: "POST",
headers: {
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
body: JSON.stringify({
"data": {
"type": "policies",
"attributes": {
"name": "Basic"
},
"relationships": {
"product": {
"data": { "type": "product", "id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4" }
}
}
}
})
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.post(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies",
headers={
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
data=json.dumps({
"data": {
"type": "policies",
"attributes": {
"name": "Basic"
},
"relationships": {
"product": {
"data": { "type": "product", "id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4" }
}
}
}
})
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies",
method: .post,
headers: [
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
],
parameters: [
"data": [
"type": "policies",
"attributes": [
"name": "Basic"
],
"relationships": [
"product": [
"data": ["type": "product", "id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4"]
]
]
]
],
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("policies", 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 = "policies",
attributes = new {
name = "Basic"
},
relationships = new {
product = new {
data = new { type = "product", id = "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4" }
}
}
}
});
 
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 "policies",
"attributes" to mapOf(
"name" to "Basic"
),
"relationships" to mapOf(
"product" to mapOf(
"data" to mapOf(
"type" to "products",
"id" to "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4"
)
)
)
)
))
 
val res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies")
.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", "policies"),
entry("attributes", ofEntries(
entry("name", "Basic")
)),
entry("relationships", ofEntries(
entry("product", ofEntries(
entry("data", ofEntries(
entry("type", "products"),
entry("id", "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4")
))
))
))
))
));
 
HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies")
.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["name"] = value::string("Basic");
 
value product_;
product_["type"] = value::string("products");
product_["id"] = value::string("3ab38aae-bbf7-4846-9c32-af9d94bf5ad4");
 
value product;
product["data"] = product_;
 
value rels;
rels["product"] = product;
 
value data;
data["type"] = value::string("policies");
data["attributes"] = attrs;
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("/policies");
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}/policies \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}' \
-d '{
"data": {
"type": "policies",
"attributes": {
"name": "Basic"
},
"relationships": {
"product": {
"data": { "type": "product", "id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4" }
}
}
}
}'

Example response / 201 Created

{
"data": {
"id": "0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
"type": "policies",
"links": {
"self": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065"
},
"attributes": {
"name": "Basic",
"duration": null,
"strict": false,
"floating": false,
"concurrent": true,
"scheme": null,
"requireProductScope": false,
"requirePolicyScope": false,
"requireMachineScope": false,
"requireFingerprintScope": false,
"requireCheckIn": false,
"checkInInterval": null,
"checkInIntervalCount": null,
"usePool": false,
"maxMachines": 1,
"maxCores": null,
"maxUses": null,
"encrypted": false,
"protected": false,
"heartbeatDuration": null,
"fingerprintUniquenessStrategy": "UNIQUE_PER_LICENSE",
"fingerprintMatchingStrategy": "MATCH_ANY",
"expirationStrategy": "RESTRICT_ACCESS",
"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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/product"
},
"data": {
"type": "products",
"id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4"
}
},
"pool": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/pool"
}
},
"licenses": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/licenses"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements"
}
}
}
}
}

linkRetrieve a policy

Retrieves the details of an existing policy.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view 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) of the policy to be retrieved.

linkReturns

A 200 OK response will be returned along with a policy 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}/policies/{ID}

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065", {
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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
headers={
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
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(
"policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
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}/policies/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.get("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/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("/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065");
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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065 \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 200 OK

{
"data": {
"id": "0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
"type": "policies",
"links": {
"self": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065"
},
"attributes": {
"name": "Premium Add-On",
"duration": 1209600,
"strict": false,
"floating": true,
"concurrent": true,
"scheme": null,
"requireProductScope": false,
"requirePolicyScope": false,
"requireMachineScope": false,
"requireFingerprintScope": false,
"requireCheckIn": false,
"checkInInterval": null,
"checkInIntervalCount": null,
"usePool": false,
"maxMachines": 5,
"maxCores": null,
"maxUses": null,
"encrypted": false,
"protected": false,
"fingerprintUniquenessStrategy": "UNIQUE_PER_PRODUCT",
"fingerprintMatchingStrategy": "MATCH_ANY",
"expirationStrategy": "RESTRICT_ACCESS",
"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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/product"
},
"data": {
"type": "products",
"id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4"
}
},
"pool": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/pool"
}
},
"licenses": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/licenses"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements"
}
}
}
}
}

linkUpdate a policy

Updates the specified policy 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) of the policy to be updated.

linkAttributes

  • linkdata.attributes.name

    string, optional

    The name of the policy.

  • linkdata.attributes.duration

    integer, optional

    The duration for the policy in seconds. When a new license implements the policy, the license's expiry is calculated with this value (i.e. time.now + policy.duration). If null, licenses will never expire. Updating this attribute will not retroactively update previously created licenses.

  • linkdata.attributes.strict

    boolean, optional

    When enabled, a license that implements the policy will be considered invalid if its machine or machine core limit is surpassed. In addition, strict requires a license to have at least 1 machine associated with it in order to pass validation.

  • linkdata.attributes.floating

    boolean, optional

    When enabled, a license that implements the policy will be valid across multiple machines. Though this is not enforced i.e. it does not invalidate a license if it's associated with more than 1 machine unless the policy is strict.

  • linkdata.attributes.concurrent

    boolean, optional

    Whether or not to allow the activation of additional machines after a given license has reached its max machine limit, i.e. machine overages. This allows a "concurrent" licensing model, where you allow a set number of machines to be activated at one time, and exceeding that limit may invalidate all current sessions. When this is disabled and a user attempts to exceed the policy's machine limit, an error response will be returned. For example, when enabled, a license with a machine limit of 3 may exceed that limit by adding 4 or more machines, though the license may then become invalid if the policy is also strict.

  • linkdata.attributes.requireProductScope

    boolean, optional

    When enabled, validating a license that implements the policy will require a product scope that matches the licenses's product relationship by its identifier (UUID).

  • linkdata.attributes.requirePolicyScope

    boolean, optional

    When enabled, validating a license that implements the policy will require a policy scope that matches the licenses's policy relationship by its identifier (UUID).

  • linkdata.attributes.requireMachineScope

    boolean, optional

    When enabled, validating a license that implements the policy will require a machine scope that matches at least 1 of the licenses's machine relationships by its identifier (UUID).

  • linkdata.attributes.requireFingerprintScope

    boolean, optional

    When enabled, validating a license that implements the policy will require a fingerprint scope that matches at least 1 of the licenses's machine relationships by its fingerprint.

  • linkdata.attributes.requireCheckIn

    boolean, optional

    When enabled, a license that implements the policy 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.

  • linkdata.attributes.checkInInterval

    string, optional

    One of day, week, month or year. The frequency at which a license should check-in.

  • linkdata.attributes.checkInIntervalCount

    integer, optional

    The number of intervals (specified in the check-in interval property) between each required check-in. For example, checkInInterval=week and checkInIntervalCount=2 requires check-in every 2 weeks. Must be a number between 1 and 365 inclusive.

  • linkdata.attributes.maxMachines

    integer, optional

    The maximum number of machines a license implementing the policy can have associated with it. This is only enforced when the policy is strict. When null, an unlimited number of machines may be associated with a license if the policy is floating. Must be a number greater than 0, and must be equal to 1 for non-floating policies.

  • linkdata.attributes.maxCores

    integer, optional

    The maximum number of machine CPU cores a license implementing the policy can have associated with it. The count is the sum of all cores for the license's machines. This is inherited from the policy. When null, a license which implements the policy can have an unlimited number of CPU cores.

  • linkdata.attributes.maxUses

    integer, optional

    The maximum number of uses a license implementing the policy can have. Cannot exceed 2,147,483,647, which is the maximum value of a 4 byte integer. When null, a license which implements the policy can have an unlimited number of uses.

  • linkdata.attributes.protected

    boolean, optional

    Whether or not the policy is protected. A protected policy disallows users the ability to create licenses themselves, useful in situations where Keygen is only managed server-side.

  • linkdata.attributes.heartbeatDuration

    integer, optional

    The custom heartbeat duration for the policy, in seconds. When a machine has an active heartbeat monitor, the machine must send a heartbeat ping within this timeframe to remain activated. Updating this attribute will not retroactively update heartbeat monitors currently in-progress, but the monitor will update itself on the next heartbeat ping.

  • linkdata.attributes.fingerprintUniquenessStrategy

    string, optional

    The uniqueness validation strategy for machine fingerprints. You can utilize this to prevent duplicate fingerprints across a variety of scopes. Updating this attribute will not retroactively update and validate previously created licenses, meaning duplicates may occur if they already exist.

    This is especially useful for disallowing trial licenses for a specific machine (i.e. device) that had previously completed a trial evaluation using another trial license.

    Options

    • UNIQUE_PER_ACCOUNT: Machine fingerprints must be unique across the entire Keygen account.
    • UNIQUE_PER_PRODUCT: Machine fingerprints must be unique across all licenses belonging to the policy's product.
    • UNIQUE_PER_POLICY: Machine fingerprints must be unique across all licenses for the policy.
    • UNIQUE_PER_LICENSE: Machine fingerprints must be unique to the license.
  • linkdata.attributes.fingerprintMatchingStrategy

    string, optional

    The matching strategy for machine fingerprints supplied during a license validation.

    Options

    • MATCH_ANY: At least 1 of the supplied machine fingerprints must match a fingerprint for the license's associated machines. E.g. if 3 fingerprints are supplied, at least 1 of them must match.
    • MATCH_MOST: The majority of supplied machine fingerprints must match the fingerprints for the license's associated machines. E.g. if 3 fingerprints are supplied, at least 2 of them must match.
    • MATCH_ALL: All supplied machine fingerprints must match the fingerprints for the license's associated machines. E.g. if 3 fingerprints are supplied, all 3 of them must match.
  • linkdata.attributes.expirationStrategy

    string, optional

    The strategy for expired licenses during a license validation and when accessing releases.

    Options

    • RESTRICT_ACCESS: Expired licenses can continue to access releases published prior to their expiry, but automatic upgrades are disabled. Validation scopes take precedence over expiry check during license validation.
    • REVOKE_ACCESS: Expired licenses are no longer able to access any releases, including past releases and upgrades. Expiry check takes precedence over scopes during license validation.
  • linkdata.attributes.metadata

    object<string, scalar>, optional

    Object containing policy metadata.

linkReturns

A 200 OK response will be returned along with the updated policy 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}/policies/{ID}

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065", {
method: "PATCH",
headers: {
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
body: JSON.stringify({
"data": {
"type": "policies",
"attributes": {
"maxMachines": 15
}
}
})
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.patch(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
headers={
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
data=json.dumps({
"data": {
"type": "policies",
"attributes": {
"maxMachines": 15
}
}
})
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
method: .patch,
headers: [
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
],
parameters: [
"data": [
"type": "policies",
"attributes": [
"maxMachines": 15
]
]
],
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(
"policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
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 = "policies",
attributes = new {
maxMachines = 15
}
}
});
 
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 "policies",
"attributes" to mapOf(
"maxMachines" to 15
)
)
))
 
val res = Unirest.patch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065")
.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", "policies"),
entry("attributes", ofEntries(
entry("maxMachines", 15)
))
))
));
 
HttpResponse<JsonNode> res = Unirest.patch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065")
.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["maxMachines"] = value::number(15);
 
value data;
data["type"] = value::string("policies");
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("/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065");
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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065 \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}' \
-d '{
"data": {
"type": "policies",
"attributes": {
"maxMachines": 15
}
}
}'

Example response / 200 OK

{
"data": {
"id": "0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
"type": "policies",
"links": {
"self": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065"
},
"attributes": {
"name": "Premium Add-On",
"duration": 1209600,
"strict": false,
"floating": true,
"concurrent": true,
"scheme": null,
"requireProductScope": false,
"requirePolicyScope": false,
"requireMachineScope": false,
"requireFingerprintScope": false,
"requireCheckIn": false,
"checkInInterval": null,
"checkInIntervalCount": null,
"usePool": false,
"maxMachines": 15,
"maxCores": null,
"maxUses": null,
"encrypted": false,
"protected": false,
"heartbeatDuration": null,
"fingerprintUniquenessStrategy": "UNIQUE_PER_LICENSE",
"fingerprintMatchingStrategy": "MATCH_ALL",
"expirationStrategy": "RESTRICT_ACCESS",
"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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/product"
},
"data": {
"type": "products",
"id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4"
}
},
"pool": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/pool"
}
},
"licenses": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/licenses"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements"
}
}
}
}
}

linkDelete a policy

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

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) of the policy 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}/policies/{ID}

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/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}/policies/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}/policies/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(
"policies/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}/policies/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}/policies/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("/policies/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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065 \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 204 No Content

No content

linkList all policies

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

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resources: either an admin or a product.

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 policies to be returned. Limit must be a number between 1 and 100.

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies?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}/policies?page[size]=15&page[number]=2
  • linkproduct

    string

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

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

linkReturns

A 200 OK response will be returned along with a list of policy 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}/policies{FILTERS}

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies?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}/policies?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}/policies?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("policies", 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}/policies")
.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}/policies")
.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("/policies");
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}/policies?limit=15 -g \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 200 OK

{
"data": [
{
"id": "0b4b1a9a-e25a-4f14-a95e-d9dd378d6065",
"type": "policies",
"links": {
"self": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065"
},
"attributes": {
"name": "Premium Add-On",
"duration": 1209600,
"strict": false,
"floating": true,
"concurrent": true,
"scheme": null,
"requireProductScope": false,
"requirePolicyScope": false,
"requireMachineScope": false,
"requireFingerprintScope": false,
"requireCheckIn": false,
"checkInInterval": null,
"checkInIntervalCount": null,
"usePool": false,
"maxMachines": 5,
"maxCores": null,
"maxUses": null,
"encrypted": false,
"protected": false,
"heartbeatDuration": null,
"fingerprintUniquenessStrategy": "UNIQUE_PER_ACCOUNT",
"fingerprintMatchingStrategy": "MATCH_ANY",
"expirationStrategy": "RESTRICT_ACCESS",
"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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/product"
},
"data": {
"type": "products",
"id": "3ab38aae-bbf7-4846-9c32-af9d94bf5ad4"
}
},
"pool": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/pool"
}
},
"licenses": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/licenses"
}
},
"entitlements": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements"
}
}
}
},
]
}

linkPop key from pool

Pop off (delete) a key from the policy's pool of pre-determined keys. The returned key is only available directly after a pop, similar to authentication tokens. This cannot be undone.

This action does not create a license resource. What you do with the key after a pop is up to you e.g. create a license with it, discard it, etc. To pop a key and create a license in a single action, simply create a license that implements the pooled policy.

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) of the policy to be retrieved.

linkReturns

A 200 OK response will be returned along with the popped key 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}/policies/{ID}/pool

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/a5a154d2-f026-40fa-bc8d-a7e3ca415298/pool", {
method: "DELETE",
headers: {
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.delete(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/a5a154d2-f026-40fa-bc8d-a7e3ca415298/pool",
headers={
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
}
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/a5a154d2-f026-40fa-bc8d-a7e3ca415298/pool",
method: .delete,
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(
"policies/a5a154d2-f026-40fa-bc8d-a7e3ca415298/pool",
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}/policies/a5a154d2-f026-40fa-bc8d-a7e3ca415298/pool")
.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}/policies/a5a154d2-f026-40fa-bc8d-a7e3ca415298/pool")
.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("/policies/a5a154d2-f026-40fa-bc8d-a7e3ca415298/pool");
req.set_method(methods::DELETE);
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl -X DELETE https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/a5a154d2-f026-40fa-bc8d-a7e3ca415298/pool \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 200 OK

{
"data": {
"id": "6331bcae-73c1-4a7e-bf02-bbf77cbb81d7",
"type": "keys",
"links": {
"self": "/v1/accounts/{ACCOUNT}/keys/6331bcae-73c1-4a7e-bf02-bbf77cbb81d7"
},
"attributes": {
"key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
"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}/policies/a5a154d2-f026-40fa-bc8d-a7e3ca415298/pool/product"
},
"data": {
"type": "products",
"id": "1f286fb6-c9bb-498b-a4e7-6c67748b1f4f"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/a5a154d2-f026-40fa-bc8d-a7e3ca415298/pool/policy"
},
"data": {
"type": "policies",
"id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
}
}
}
}
}

linkPolicy relationships

Relationship endpoints for the policy resource.

linkAttach policy entitlements

Attach entitlements to a policy. This will immediately be taken into effect for all future license validations. Any license that implements the given policy will automatically possess all the policy's entitlements.

Below are the limitations to attaching an entitlement:

  • You cannot attach an already attached entitlement.

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 key of the policy to be updated. Cannot be a legacy encrypted policy key.

linkReturns

A 201 Created response will be returned along with an array of policy entitlement 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}/policies/{ID}/entitlements

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements", {
method: "POST",
headers: {
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
body: JSON.stringify({
"data": [
{
"type": "entitlements",
"id": "57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
}
]
})
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.post(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements",
headers={
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
data=json.dumps({
"data": [
{
"type": "entitlements",
"id": "57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
}
]
})
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements",
method: .post,
headers: [
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
],
parameters: [
"data": [
[
"type": "entitlements",
"id": "57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
]
]
],
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(
"policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements",
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 = "entitlements",
id = "57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
}
]
});
 
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 listOf(
mapOf(
"type" to "entitlements",
"id" to "57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
)
)
))
 
val res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements")
.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;
import static java.util.List.of;
 
JSONObject body = new JSONObject(ofEntries(
entry("data", of(
ofEntries(
entry("type", "entitlements"),
entry("id", "57f1ceb4-6bf4-44dd-8967-de88364bf9eb")
)
))
));
 
HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements")
.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 entl;
entl["type"] = value::string("entitlements");
entl["id"] = value::string("57f1ceb4-6bf4-44dd-8967-de88364bf9eb");
 
value data = value::array(1);
data[0] = entl;
 
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("/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements");
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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}' \
-d '{
"data": [
{
"type": "entitlements",
"id": "57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
}
]
}'

Example response / 201 Created

{
"data": [
{
"id": "14fb3e6a-2b30-42b4-b2ff-06ca2e6c0608",
"type": "policy-entitlements",
"attributes": {
"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}"
}
},
"entitlement": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/entitlements/57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
},
"data": {
"type": "entitlements",
"id": "57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
}
},
"policy": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065"
},
"data": {
"type": "policies",
"id": "0b4b1a9a-e25a-4f14-a95e-d9dd378d6065"
}
}
},
"links": {
"related": "/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements/57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
}
}
]
}

linkDetach policy entitlements

Detach entitlements from a policy. This will immediately be taken into effect for all future license validations.

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 key of the policy to be updated. Cannot be a legacy encrypted policy 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}/policies/{ID}/entitlements

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements", {
method: "DELETE",
headers: {
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
body: JSON.stringify({
"data": [
{
"type": "entitlements",
"id": "57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
}
]
})
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.delete(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements",
headers={
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
},
data=json.dumps({
"data": [
{
"type": "entitlements",
"id": "57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
}
]
})
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements",
method: .delete,
headers: [
"Content-Type": "application/vnd.api+json",
"Accept": "application/vnd.api+json",
"Authorization": "Bearer {TOKEN}"
],
parameters: [
"data": [
[
"type": "entitlements",
"id": "57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
]
]
],
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(
"policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements",
Method.DELETE
);
 
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 = "entitlements",
id = "57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
}
]
});
 
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 listOf(
mapOf(
"type" to "entitlements",
"id" to "57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
)
)
))
 
val res = Unirest.delete("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements")
.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;
import static java.util.List.of;
 
JSONObject body = new JSONObject(ofEntries(
entry("data", of(
ofEntries(
entry("type", "entitlements"),
entry("id", "57f1ceb4-6bf4-44dd-8967-de88364bf9eb")
)
))
));
 
HttpResponse<JsonNode> res = Unirest.delete("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements")
.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 entl;
entl["type"] = value::string("entitlements");
entl["id"] = value::string("57f1ceb4-6bf4-44dd-8967-de88364bf9eb");
 
value data = value::array(1);
data[0] = entl;
 
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("/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements");
req.set_method(methods::DELETE);
req.set_body(body.serialize());
 
client.request(req)
.then([](http_response res)
{
auto data = res.extract_json().get();
})
.wait();
curl -X DELETE https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}' \
-d '{
"data": [
{
"type": "entitlements",
"id": "57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
}
]
}'

Example response / 204 No Content

No Content

linkList policy entitlements

Returns a list of entitlements attached to the policy. The entitlements are returned sorted by creation date, with the most recent entitlements appearing first.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view 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 key of the license to list entitlements for. Cannot be a legacy encrypted license key.

linkFilters

  • linklimit

    integer, default is10

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

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements?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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements?page[size]=15&page[number]=2

linkReturns

A 200 OK response will be returned along with a list of entitlement 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}/policies/{ID}/entitlements{FILTERS}

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements?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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements?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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements?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("entitlements", Method.GET);
 
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer {TOKEN}");
 
request.AddParameter("list", 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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements")
.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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements")
.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("/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements");
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}/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements?limit=15 -g \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {TOKEN}'

Example response / 200 OK

{
"data": [
{
"id": "db1ff21b-f42f-4623-952b-ca7f2600bded",
"type": "entitlements",
"attributes": {
"name": "Example Feature",
"code": "EXAMPLE_FEATURE",
"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}"
}
}
},
"links": {
"self": "/v1/accounts/{ACCOUNT}/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded"
}
},
]
}