menu

linkAPI Reference

The Keygen API is organized around REST principles. All requests must be made over TLS/SSL. In addition, all request and response bodies, including errors, are encoded in JSON format.

The API has predictable, resource-oriented URLs, and uses standard HTTP response codes to indicate API errors. We use built-in HTTP features, like authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from any client-facing software application.

code Get Started with our API

linkYour Keygen Account

In order to make requests to our licensing API, you will need to use your Keygen account's unique ID, or its slug that you chose during sign up. Every API request will utilize your account's ID or slug within the URL path, i.e. /v1/accounts/{ID} or /v1/accounts/{SLUG}. Your account's ID and slug can be used interchangably as URL params.

You can find your account's ID and slug in your account settings, under the "Current Account" section.

Account Permissions

By default, your Keygen account will allow public user registration, user token generation (authentication), and will also allow users to create their own licenses and machines while authenticated. This is referred to as an "unprotected" account, allowing client-side resource management (i.e. by your users), while you respond to those events using webhooks.

For example, you can allow users to create and delete their licenses and machine activations, while you respond to those events to handle billing, e.g. charge them for new licenses, update their subscription to match their license and machine count, etc.

If you do not want your users to be able to create and manage their own licenses and machines client-side (which may necessitate listening for webhook events) then you should set your account to "protected", which will require admin authentication to create and manage all resources, aside from machine activation and deactivation.

Setting your account to "protected" is the recommended approach when using Keygen 100% server-side. You can change your account permissions from your account settings page.

See the security section for more tips.

linkAccepted Content Types

Our JSON API accepts the following content types specified via the HTTP Content-Type header:

  • application/vnd.api+json
  • application/json

In addition, our JSON API is able to respond with the following content types specified via the HTTP Accept header:

  • application/vnd.api+json
  • application/json

By default our API will respond with application/vnd.api+json, unless asked otherwise through the standard HTTP Accept header. All other content types will be rejected with a 400 status code.

linkClient Libraries

At the moment we're focused on our HTTP API endpoints. As time goes by we'll be featuring here some more of our open-source clients for different languages and frameworks, as well as those contributed by the community.

We're still exploring what an official client library from Keygen would look like, how we could ensure cross-platform interoperability, and how to build it securely. The more pieces applications implementing Keygen share, the harder it will be to prevent software cracking, i.e. with an official client library, a well-made crack for one application runs the risk of working across multiple applications using Keygen.

For now, we recommend using an HTTP library to directly interface with our API from your application code, or to discreetly integrate Keygen server-side.

Open Source Client Libraries

If you have written one yourself, please let us know. We will feature your name along with the client library, unless asked to do otherwise.

Language
Nothing here yet
We will collaborate with project maintainers to keep open source libraries up-to-date as our systems evolve. If you would like us to add documentation examples for a specific language, or if you would like us to add an open-source library you created, please email [email protected].

Alternative HTTP Libraries

We use the following open-source HTTP libraries for code examples:

Language
Node node-fetch by bitinn
Python Requests by psf
Swift Alamofire
C# RestSharp
Kotlin Unirest by mashape
Java Unirest by mashape
C++ C++ REST SDK by Microsoft
Shell cURL

You may of course choose to use a different HTTP library, but these are the libaries that you will see used throughout our documentation.

linkPre-populated Examples

When you're logged in to your dashboard, your authentication token is pre-populated in all the examples on this page so you can test any example right away. Only you can see these values. All other values, such as license IDs, and license keys still need to be replaced with real values.

The pre-populated token is an admin token and is not meant to be used in client-facing code, stored in version control, and so forth.

linkVersioning

When we introduce breaking changes to the API, we will release a new numbered version, e.g. we will go from v1 to v2. The current version is v1. All changes will be detailed within our changelog.

linkAPI Stability

We will not introduce breaking changes into the API without bumping the current version. You can rest assured that the endpoints you're utilizing within your product are stable.

Keep in mind that stable does not mean complete. We could potentially add new resources and actions, but existing resources will remain unchanged.

linkBackwards Compatibility

What do we consider to be “backwards-compatible” changes?

  • Adding new API resources
  • Adding new optional request parameters to existing API endpoints
  • Adding new properties to existing API resources and responses
  • Changing the order of properties in existing API responses
  • Changing the length or format of resource IDs, future tokens, future auto-generated license keys, or other opaque strings (this includes adding or removing prefixes)
  • You can safely assume resource IDs we generate will never exceed 255 characters (but you should be able to handle IDs of up to that length)
  • Adding new event types (your webhook listeners should gracefully handle unfamiliar events types)

linkSecurity

Below you will find various security tips you may find useful.

linkSecret API Tokens

If one of your admin API tokens become compromised, you can quickly revoke it from your admin dashboard.

In Client-facing Software

Do not embed your admin or product API tokens within client- or end-user-facing code. If you're using Keygen client-side, do not embed your admin or product tokens within your product's source code. Doing so exposes your tokens and opens your account up to attackers, regardless of how obfuscated the token is.

Instead, you can perform license and machine creation requests client-side while authenticated as one of your users, or by using an activation token which belongs to the license you're activating a machine for.

If you're using Keygen server-side, keep your secret API tokens safe.

In Version Control

We recommend that you do not store your API tokens in version control. It is recommended that you store tokens in an environment file that is never checked into the repository, or directly within the ENV on non-public devices.

linkPublic IDs and Keys

Embedding account, product and policy IDs directly into your product i.e. client-side code is perfectly safe. Inlining your public key is also perfect safe. In fact, you won't be able to communicate with Keygen's API or verify signatures unless you include some of these values, and managing e.g. feature licenses without being able to embed policy IDs wouldn't be feasible.

With that in mind, it is recommended that you use your account ID over your account slug, as unlike your account slug, your ID is unchangable.

Resource IDs are standard v4 UUIDs, resembling the following format:

1fddcec8-8dd3-4d8d-9b16-215cac0f9b52

An account's RSA public key will resemble the following:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzPAseDYupK78ZUaSbGw7
YyUCCeKo/1XqTACOcmTTHHGgeHacLK2j9UrbTlhW5h8Vyo0iUEHrY1Kgf4wwiGgF
h0Yc+oDWDhq1bIertI03AE420LbpUf6OTioX+nY0EInxXF3J7aAdx/R/nYgRJrLZ
9ATWaQVSgf3vtxCtCwUeKxKZI41GA/9KHTcCmd3BryAQ1piYPr+qrEGf2NDJgr3W
vVrMtnjeoordAaCTyYKtfm56WGXeXr43dfdejBuIkI5kqSzwVyoxhnjE/Rj6xks8
ffH+dkAPNwm0IpxXJerybjmPWyv7iyXEUN8CKG+6430D7NoYHp/c991ZHQBUs59g
vwIDAQAB
-----END PUBLIC KEY-----

linkAccount Permissions

If you do not want your users to be able to create and manage their own licenses and machines (which could necessitate listening for webhook events) then you should set your account to protected, which will require admin authentication to create and manage all resources, aside from token creation and license validation. Setting your account to protected can be done within your account settings.

Alternatively, you can set individual licenses policies to protected (which by default is inherited from the account's current protected state), which will only disallow users from creating and managing licenses which implement that particular policy and their associated machines, rather than all resources e.g. public user creation, licenses that implement other unprotected policies, etc. You can also set a license to protected, which will disallow machine activation/deactivation; similar to policies, the license's protected attribute is inherited from its policy.

By default, your account is unprotected, which allows user registration as well as the ability for users to manage their own resources.

linkValidation Permissions

If you only need to validate license keys, then you do not need to implement user creation or authentication. The license validate-key action does not require authentication. If you're doing anything else e.g. validating multiple license resources per-user, tracking machines, etc., user authentication or an activation token will be required in order to perform these API operations client-side.

You can add required validation scopes to your policies to e.g. require a machine fingerprint, etc., which helps implement certain license models without the need for any additional server-side logic such as a webhook handler.

linkCrack Prevention

Although all applications are susceptible to cracking (given enough motivation), there are certain things you can do to make cracking harder. Even applications written in a compiled language, such as C, are susceptible to software cracking.

Efforts beyond the prevention measures below have diminishing returns for most software products and time is better spent on legitimate users. Reach out to [email protected] if you need additional anti-cracking measures, we'd be happy to chat with you.

Signature Verification

To help prevent tampering and other types of attacks such as a man-in-the-middle attack, you may choose to implement license key signature verification, and request signature verification. Both of these verifications harden your software by ensuring the given data originated from Keygen and that the values have not been modified.

The easiest one of those to implement is request signature verification, which can also be used offline with license validation caching.

User Agent Header

We recommend that you supply a custom User-Agent header with all API requests from your software application. You should include your organization name, the application's name, the running version number of the application, the operating system name, in addition to any other information you may find valuable.

Application-Name/1.33.7 (Org-Name) darwin/10.15.5 (macOS Catalina) Apache-HttpClient/4.5.5 (Java/1.8.0_201)

We will use this value to automatically detect cracking attempts. We will notify you of all findings and help you secure your application.

We are currently running a 'pilot' for an AI/ML crack detection product. If this is something your organization is interested in, please reach out to us: [email protected]. We'd love to see if you're a good fit.

linkResponse Codes

Our API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a validation failed, etc.), and codes in the 5xx range indicate an error with our servers (these are rare).

Code Status Meaning
200 OK Everything worked as expected.
201 Created The resource was created successfully.
202 Accepted The request has been accepted for processing.
204 No content Everything worked as expected, but there was nothing to respond with.
400 Bad Request The request was unacceptable, often due to missing or unpermitted parameters.
401 Unauthorized No valid API token provided.
403 Forbidden The authenticated entity does not have permission to complete the request.
404 Not Found The requested resource doesn't exist.
409 Conflict The request could not be completed because the resource already exists.
422 Unprocessable Entity A validation error occurred on the resource.
429 Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
5xx Server Errors Something went wrong on our end. (These are rare.)

linkErrors

Below you will find the various attributes for request errors.

linkAttributes

  • linktitle

    string

    A short, human-readable summary of the problem.

  • linkdetail

    string

    A more detailed human-readable explanation of the problem.

  • linkcode

    string

    A unique, unchanging machine-readable error code. This may or may not be included in the error payload, depending on the type of error.

  • linksource

    hash<string, any>

    A hash containing references to the source of the error. This may or may not be included in the error payload, depending on the type of error.

  • linksource.pointer

    string

    A pointer to the problem data, e.g. "/data" for the primary data, "/data/attributes/email" for a specific attribute, or "/data/relationships/user" for a problem with a relationship. This may or may not be included in the error payload, depending on the type of error.

  • linksource.parameter

    string

    A string indicating which URI query parameter caused the error. This may or may not be included in the error payload, depending on the type of error.

Example error

{
  "errors": [
    {
      "title": "Unprocessable entity",
      "detail": "must be a valid email",
      "code": "EMAIL_INVALID",
      "source": {
        "pointer": "/data/attributes/email"
      }
    },
    …
  ]
}

linkAuthentication

Requests are authenticated using a bearer token in an Authorization header. Within the header, you will utilize a Token resource's token attribute, like so,

Authorization: Bearer {TOKEN}

If you want to interact with Keygen's API client-side, then you should do so using our user resources, which we created for this purpose. You can create users with email and password credentials, which can be used during token generation to authenticate a user.

After a user is authenticated, they can interact with our API in a way that is limited to only their user profile.

There are a couple other token types in addition to admin/user authentication tokens:

  • Activation tokens: authenticating as a license is useful when you're not utilizing our user resources for authentication, but you still want to perform client-side machine activation. Activation tokens allow a limited number of machine activations and deactivations. To create a new activation token, please see the License token relationship.
  • Product tokens: authenticating as a product is useful in server-side environments. These tokens allow full management of resources associated with the given product. To create a new product token, please see the Product token relationship.

All user tokens have a 2 week expiry and can be regenerated as needed during that timeframe. Admin and product tokens do not expire, and should only be used server-side. By default, activation tokens do not expire, but you may set an expiry during creation if desired.

Admin and product tokens should only be used server-side, this is because they allow full near management of your Keygen account. This means that if an attacker were to obtain a product token from within your code, no matter how obfuscated, they will be able to create and manage licenses at-will—including those of your other customers.

Most API endpoints will require authentication, and access to resources depends on the token bearer's authorization and role.

You can manage tokens using the Tokens resource.

Security Warning

Tokens should be treated as passwords. Different tokens carry different privileges depending on the bearer of the token, so be sure to keep them secret! Do not share your admin or product API tokens in publicly accessible areas such as GitHub, client-facing code, and so forth. If in doubt, please regenerate or revoke the offending token(s).

linkAuthorization

Access to certain resources is dependent upon a token bearer's role. Most of the time you will be authenticating as one of your users, which will allow access to a small subset of resources available to your account. In other cases, as when you are using a server-side integration, you may be authenticating as a product, or even an admin; in these cases, you will have access to a wider range of resources.

Resource attributes and relationships marked with a "protected" badge are only allowed to be specified if the authenticated bearer is an admin of the account, or a product that owns the specified resource. Attributes and relationships marked with a "read only" badge can not be modified.

Many resource endpoints are automatically scoped according to the token bearer's role. For example, listing all licenses while authenticated as a product will only list licenses associated with that particular product. Attempting to access resources that the bearer does not have access to will respond with a 403 forbidden error.

Never hard-code authentication tokens within your client-facing product – doing so could leave your product open to major exploitations by allowing a malicious user the ability to fully manage your account's resources. The only time you should be using your admin or product token(s) directly is if you are working with Keygen server-side.

Here's a quick summary of the different authorization roles:

Role Administrator Authentication Authorization
None No No Unauthenticated users can create a new user profile (unless your account is protected), and validate license keys using the validate-key action. No other endpoints are accessisible to unauthenticated users.
User No Yes Authenticated users may access certain resource endpoints, but all resources that are returned will be scoped to their user profile, e.g. when a user makes a request to list all licenses, only the licenses which are associated with their user profile will be returned.
License No Yes Authenticated licenses may perform machine activations and deactivations through activation tokens. They may also validate the license. They cannot perform any other request.
Product Yes Yes Authenticated products may access resources for their account that are associated with that particular product. All resources that are returned will be scoped to the product, e.g. when a product makes a request to list all licenses, only the licenses which are associated with the product will be returned.
Support Agent Yes Yes Authenticated support agents may access some resources for their account. They can read the following resources: products, policies, users, licenses, machines. They can update the following resources: licenses, machines. They cannot delete resources.
Sales Agent Yes Yes Authenticated sales agents may access some resources for their account. They can read the following resources: products, policies, users, licenses, machines. They can create the following resources: policies, licenses, machines. They can update the following resources: policies, licenses, machines. They can delete the following resources: licenses, machines. They cannot delete any other resources.
Developer Yes Yes Authenticated developers may access all resources for their account, minus account billing information.
Admin Yes Yes Authenticated admin users may access all resources for their account.

linkRate Limiting

For client-side requests, i.e. made unauthenticated, or with a user or activation token, a single IP address can make a maximum burst of 60 requests per 30 second window and 500 requests per 5 minute window, which allows for 1 request/sec with short bursts of up to 3-5 requests/sec. For server-side environments, i.e. requests authenticated with admin and product tokens, these limits are higher, based on your server-side usage.

We may add additional rate limit windows in the future, which will be included within the X-RateLimit-Window header with a specific name, e.g. 30s.

If we see patterns of abuse, this limit may be lowered or the IP may be temporarily blacklisted. In rare cases of significant abuse, the IP may be permanently blacklisted from our API.

Looking for more customized rate limit? Reach out to our support team and we can discuss a custom rate limit that will work with your requirements.

When rate limited, a 429 HTTP status code will be given. You can also check the returned HTTP headers of any API request to see your current rate limit status for the closest window:

Header Description
X-RateLimit-Window The current rate limiting window that is closest to being reached, percentage-wise.
X-RateLimit-Count The number of requests that have been performed within the current rate limit window.
X-RateLimit-Limit The maximum number of requests that the IP is permitted to make for the current window.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.

Example response / 429 Too Many Requests

X-RateLimit-Window: 5m
X-RateLimit-Count: 501
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1490973281
{
  "errors": [
    {
      "title": "Throttle limit reached",
      "detail": "Throttle limit has been reached for your IP address."
    }
  ]
}

linkRelationships

Throughout the API, many resources will have a relationships hash containing another resource which they are associated with. When creating or modifying a relationship, you will be introduced to what's called a "resource identifier object", or linkage for short.

A "resource identifier object" is a hash that identifies an individual resource. The linkage hash must contain a type and an id of the individual resource for the relationship.

Example resource identifier object

{
  "type": "policies",
  "id": "76805397-9b46-4dcf-ad90-177a0f0969e2"
}

linkMetadata

Many resources including products, users, licenses, machines and policies have a metadata attribute. You can use this attribute to attach key-value data to the given resource.

Metadata is useful for storing additional, structured information on an object. As an example, you could store your user's zipcode, their id within your own database (if applicable), or their Stripe customer_id for billing purposes.

Since the metadata attribute is simply a key-value store (hash), all write operations will overwrite the entire hash, so be sure to merge existing data on your end when performing updates.

Do not attach sensitive billing information directly to resources using the metadata attribute. Doing so is a violation of our terms of use. If you're using Stripe, you need only attach their Stripe customer_id, or a temporary secure representation of a card (such as a stripe_token), which can then be used to look up their information server-side when required.

You may specify up to 64 metadata keys, with key names up to 256 characters in length and with values up to 512 characters in length.

Key Transformation

Please note: all keys will be transformed into lower camelcase (exampleKey), so we recommend using lower camelcase when possible. For example, example_key will be transformed into exampleKey, ExampleKey will also be transformed into exampleKey, etc.

Example Use Cases

Here's a few example metadata use cases:

Use Case
Link IDs Attach your system's unique IDs to a Keygen object, for easy lookups. For example, add an order number for a license, Stripe customer and subscription IDs, or the customer's user ID in your system.
License entitlements Store information about what features or actions a license is allowed to perform.
Customer details Annotate a user by storing additional details such as company name for later use.

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/a5a154d2-f026-40fa-bc8d-a7e3ca415298", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "licenses",
      "attributes": {
        "metadata": {
          "customerEmail": "[email protected]",
          "customerId": "cust_a7e3ca415298f0",
          "isPro": true
        }
      }
    }
  })
})

const { data, errors } = await response.json()
import requests
import json

res = requests.patch(
  "https://api.keygen.sh/v1/accounts/<%= account %>/licenses/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  headers={
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  data=json.dumps({
    "data": {
      "type": "licenses",
      "attributes": {
        "metadata": {
          "customerEmail": "[email protected]",
          "customerId": "cust_a7e3ca415298f0",
          "isPro": true
        }
      }
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  method: .patch,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "licenses",
      "attributes": [
        "metadata": [
          "customerEmail": "[email protected]",
          "customerId": "cust_a7e3ca415298f0",
          "isPro": true
        ]
      ]
    ]
  ],
  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/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  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 {
      metadata = new {
        customerEmail = "[email protected]",
        customerId = "cust_a7e3ca415298f0",
        isPro = true
      }
    }
  }
});

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(
      "metadata" to mapOf(
        "customerEmail" to "[email protected]",
        "customerId" to "cust_a7e3ca415298f0",
        "isPro" to true
      )
    )
  )
))

val res = Unirest.patch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/a5a154d2-f026-40fa-bc8d-a7e3ca415298")
  .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("metadata", ofEntries(
        entry("customerEmail", "[email protected]"),
        entry("customerId", "cust_a7e3ca415298f0"),
        entry("isPro", true)
      ))
    ))
  ))
));

HttpResponse<JsonNode> res = Unirest.patch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/a5a154d2-f026-40fa-bc8d-a7e3ca415298")
  .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 metadata;
metadata["customerEmail"] = value::string("[email protected]");
metadata["customerId"] = "cust_a7e3ca415298f0";
metadata["isPro"] = true;

value attrs;
attrs["metadata"] = metadata;

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/a5a154d2-f026-40fa-bc8d-a7e3ca415298");
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/a5a154d2-f026-40fa-bc8d-a7e3ca415298 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "licenses",
          "attributes": {
            "metadata": {
              "customerEmail": "[email protected]",
              "customerId": "cust_a7e3ca415298f0",
              "isPro": true
            }
          }
        }
      }'

linkPagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance you can list users, list licenses, and list machines. These list API methods share a common format, taking an optional page query parameter.

Our API utilizes a page-based strategy via the page[size] and page[number] parameters. All results are returned in reverse chronological order.

linkParameters

  • linkpage

    hash<string, integer>

    Hash containing page size and page number.

  • linkpage.size

    integer

    The page size. Must be a number between 1 and 100.

  • linkpage.number

    integer

    The page number.

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users?page[size]=25&page[number]=2", {
  method: "GET",
  headers: {
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, links, errors } = await response.json()
import requests
import json

res = requests.get(
  "https://api.keygen.sh/v1/accounts/<%= account %>/users?page[size]=25&page[number]=2",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users?page[size]=25&page[number]=2",
  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("users", Method.GET);

request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer <%= token %>");

request.AddParameter("page[size]", 25);
request.AddParameter("page[number]", 2);

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 %>/users")
  .header("Authorization", "Bearer <%= token %>")
  .header("Accept", "application/vnd.api+json")
  .queryString("page[size]", 25)
  .queryString("page[number]", 2)
  .asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;

HttpResponse<JsonNode> res = Unirest.get("https://api.keygen.sh/v1/accounts/<%= account %>/users")
  .header("Authorization", "Bearer <%= token %>")
  .header("Accept", "application/vnd.api+json")
  .queryString("page[size]", 25)
  .queryString("page[number]", 2)
  .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("/users");
uri.append_query("page[size]", 25);
uri.append_query("page[number]", 2);

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 %>/users?page[size]=25&page[number]=2' -g \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response

{
  "data": [
    {
      "id": "6ed498fe-5f5f-49af-82ee-cb7400cc4522",
      "type": "users",
      "links": {
        "self": "/v1/accounts/<%= account %>/users/6ed498fe-5f5f-49af-82ee-cb7400cc4522"
      },
      "attributes": {
        "fullName": "Marty McFly",
        "firstName": "Marty",
        "lastName": "McFly",
        "email": "[email protected]",
        "role": "user",
        "metadata": {},
        "created": "2017-01-02T19:48:50.077Z",
        "updated": "2017-01-02T19:48:50.077Z"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        },
        "products": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
          }
        },
        "licenses": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
          }
        },
        "machines": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
          }
        },
        "tokens": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
          }
        }
      }
    },
    …
  ],
  "links": {
    "self": "/v1/accounts/<%= account %>/users?page[size]=25&page[number]=2",
    "prev": "/v1/accounts/<%= account %>/users?page[size]=25&page[number]=1",
    "next": "/v1/accounts/<%= account %>/users?page[size]=25&page[number]=3",
    "first": "/v1/accounts/<%= account %>/users?page[size]=25&page[number]=1",
    "last": "/v1/accounts/<%= account %>/users?page[size]=25&page[number]=4",
    "meta": {
      "pages": 4,
      "total": 98
    }
  }
}

linkIdempotency

Some resources, such as webhook events may contain an idempotency token inside of a meta hash. In the case of webhook events, these tokens allow you to safely retry events without accidentally responding to the same event multiple times.

linkExample scenario

When a user creates a new license, you would want to make sure that the license.created webhook event that you're listening for would only be acted upon once, regardless of how many times you retry the event, to guarantee you only charge your user for a single license.

You can accomplish this by logging the idempotency token (to a database, for example, Redis) and ignoring future webhook events that come through with an identical token, signaling a retried event.

Although retrying a webhook event creates a new resource, the idempotency token will stay the same throughout the event's lifetime.

Example resource

A failed webhook event resource.

{
  "data": {
    "id": "2bc99fe1-f315-4877-ac5f-542240c4e883",
    "type": "webhook-events",
    "meta": {
      "idempotencyToken": "e8e0fbb598e8bcfd0e94ceb79199edc79e6ab53f4a4bbb32d7aede7964e7c3v2",
    },
    "links": {
      "self": "/v1/accounts/<%= account %>/webhook-events/2bc99fe1-f315-4877-ac5f-542240c4e883"
    },
    "attributes": {
      "endpoint": "https://example.com/webhooks",
      "payload": "{\"data\":{…}}",
      "event": "license.created",
      "status": "failed",
      "lastResponseCode": 500,
      "lastResponseBody": "Internal Server Error",
      "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 %>"
        }
      }
    }
  }
}

Example request

Retry the above failed webhook event resource.

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events/2bc99fe1-f315-4877-ac5f-542240c4e883/actions/retry", {
  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 %>/webhook-events/2bc99fe1-f315-4877-ac5f-542240c4e883/actions/retry",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/webhook-events/2bc99fe1-f315-4877-ac5f-542240c4e883/actions/retry",
  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(
  "webhook-events/2bc99fe1-f315-4877-ac5f-542240c4e883/actions/retry",
  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 %>/webhook-events/2bc99fe1-f315-4877-ac5f-542240c4e883/actions/retry")
  .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 %>/webhook-events/2bc99fe1-f315-4877-ac5f-542240c4e883/actions/retry")
  .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("/webhook-events/2bc99fe1-f315-4877-ac5f-542240c4e883/actions/retry");
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 %>/webhook-events/2bc99fe1-f315-4877-ac5f-542240c4e883/actions/retry \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response

Notice that it's a new resource, yet the idempotency token matches the original event.

{
  "data": {
    "id": "1bda5fd5-6d82-49f5-b5b8-71bb432a32bb",
    "type": "webhook-events",
    "meta": {
      "idempotencyToken": "e8e0fbb598e8bcfd0e94ceb79199edc79e6ab53f4a4bbb32d7aede7964e7c3v2",
    },
    "links": {
      "self": "/v1/accounts/<%= account %>/webhook-events/1bda5fd5-6d82-49f5-b5b8-71bb432a32bb"
    },
    "attributes": {
      "endpoint": "https://example.com/webhooks",
      "payload": "{\"data\":{…}}",
      "event": "license.created",
      "status": "queued",
      "lastResponseCode": null,
      "lastResponseBody": null,
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      }
    }
  }
}

linkChecking Connectivity

You can detect network connectivity and check if our licensing servers are accessible for the current network environment by sending a GET request to the ping endpoint. The API endpoint will respond with a 200 HTTP status code.

Definition

https://api.keygen.sh/v1/ping

Example request

Ping our licensing servers.

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/ping", { method: "GET" })
import requests

res = requests.get("https://api.keygen.sh/v1/ping")
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/ping", method: .get)
using RestSharp;

var client = new RestClient("https://api.keygen.sh");
var request = new RestRequest("/v1/ping", Method.GET);
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/ping")
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;

HttpResponse<JsonNode> res = Unirest.get("https://api.keygen.sh/v1/ping");
#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");
http_request req;

req.set_request_uri("/v1/ping");
req.set_method(methods::GET);

client.request(req).wait();
curl -X GET https://api.keygen.sh/v1/ping

Example response / 200 OK

No content

linkCryptography

Each Keygen account is equipped with its own unique RSA 2048-bit public/private keypair, which is used in signing response payloads using RSA-SHA256, and which can also be used to sign or encrypt license keys for added security and offline license verification using schemes. The scheme used for license key signing and encryption will depend on the cryptographic scheme that the particular policy implements.

You can find your account's public key within your dashboard settings page, which you can use to verify response payloads and license keys. Private keys are kept securely encrypted on our servers.

To see an example of cryptographic validation, check out our example on GitHub. It will show you how to utilize your account's public key to validate various cryptographic license key schemes.

linkCryptographic keys

Below you will find information on various license key encryption and signature schemes. These can be used verified in offline or air-gapped environments, or to increase security and confidence for embedded key datasets. Most embedded datasets have a default, but they can be changed to include more data, or less data. The sky's the limit.

Once a license key is created, it cannot be changed, i.e. license keys are immutable. This means the dataset that 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 crafting your embedded dataset. If you plan on renewing licenses after or before an expiration date, you may wish to embed the amount of time a license is allowed to be used offline, e.g. a numeric duration such as 1 year, instead of a hard expiration date.

If you need to change the dataset, e.g. to extend an embedded expiration date after renewal, a new license key will need to be created. This is not a limitation of cryptographic keys or of Keygen, but a feature of cryptography which actually shows how keys are 100% tamper-proof — any data modification invalidates the signature.

Cryptographic keys can be used as a typical 'license file.' You can pack them up as a text file and distribute them to your users. The integrity of the file can then be verified by verifying the key's signature, or decrypting the key value. Some businesses prefer this over distributing the relatively large cryptographic key in text form.

linkRSA_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. We recommend verifying with a salt length of auto when available.

key/eyJhY2NvdW50Ijp7ImlkIjoiZmE0ZTIyYzYtNDM2Zi00MTM0LWI5NzYtNzlkZjkxMGFjZjY5In0sInByb2R1Y3QiOnsiaWQiOiIyYzAzNWNkZS1hYTFiLTQ3YzEtYmRiZS1kZjBiMjlkOGM1ZmIifSwicG9saWN5Ijp7ImlkIjoiNmUyOTU4MGYtYTNlYi00OWUzLTg4MjAtZjZlMDNhZTkyMzBiIiwiZHVyYXRpb24iOm51bGx9LCJ1c2VyIjpudWxsLCJsaWNlbnNlIjp7ImlkIjoiZmQyOTNiZTEtZjYwNS00MjJkLWEwMjItMzc5NDZmNThjMGZkIiwiY3JlYXRlZCI6IjIwMjEtMDMtMjJUMTI6NDY6MTguMjE3WiIsImV4cGlyeSI6bnVsbH19.ZIXTH2HhILamEedSXoFSn9EFloOOUtPulq37T7YnJJolRF18-NaMb7L22ozG2v1NtioX5ZK20iSmGnTy6dLsPjaK3PpM1gL4BAD4yQuU979EuyAz7j169lpiyBtx7ytOTIJ_hr1aAMotl97BY8mBQAn-ASctNnmLqeYD0IvVniMBPes64FM5GPfyK8IIdfX23XRue3HW1nHiPBFvmiaH-_WSY81cl6fQYdrmbGJn0FSP9QYK2-CCsw1OzE_q47YmH5-Z_-VzfFnEBWLsrSvlz3HRlD5N6QhT_kl4jkN-7hou76vS1-P_DN-VD5rNXQSxKxPnbFvtSIX3rk0WCSw3rQ==

The final signed key consists of the following format:

SIGNING_PREFIX = "key"
SIGNING_DATA = "{SIGNING_PREFIX}/{BASE64_DATASET}"
BASE64_SIGNATURE = rsa_pkcs1_pss_sign(SIGNING_DATA)

"{SIGNING_DATA}.{BASE64_SIGNATURE}"

An embedded dataset may be given during license creation via the key attribute. This dataset will be used to create the key signature, and it will be encoded for easier transfer. It can be decoded within your software and its authenticity can be verified cryptographically. The default dataset is a JSON object, as follows:

{
  "account": {
    "id": "fa4e22c6-436f-4134-b976-79df910acf69"
  },
  "product": {
    "id": "2c035cde-aa1b-47c1-bdbe-df0b29d8c5fb"
  },
  "policy": {
    "id": "6e29580f-a3eb-49e3-8820-f6e03ae9230b",
    "duration": null
  },
  "user": null,
  "license": {
    "id": "fd293be1-f605-422d-a022-37946f58c0fd",
    "created": "2021-03-22T12:46:18.217Z",
    "expiry": null
  }
}

The user property may be null depending on the license's user relationship. The license's expiry and policy's duration attributes may also be null if the license does not expire.

linkRSA_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.

key/eyJhY2NvdW50Ijp7ImlkIjoiZmE0ZTIyYzYtNDM2Zi00MTM0LWI5NzYtNzlkZjkxMGFjZjY5In0sInByb2R1Y3QiOnsiaWQiOiIyYzAzNWNkZS1hYTFiLTQ3YzEtYmRiZS1kZjBiMjlkOGM1ZmIifSwicG9saWN5Ijp7ImlkIjoiNmUyOTU4MGYtYTNlYi00OWUzLTg4MjAtZjZlMDNhZTkyMzBiIiwiZHVyYXRpb24iOjMxNTU2OTUyfSwidXNlciI6eyJpZCI6ImE0OTliYjkzLTk5MDItNGI1Mi04YTA0LTc2OTQ0YWQ3ZjY2MCIsImVtYWlsIjoidXNlckBrZXlnZW4uZXhhbXBsZSJ9LCJsaWNlbnNlIjp7ImlkIjoiZjJjNjU2MDItOTJhOC00MTFmLTlmZWYtZWRhMGE2NjJmOWI2IiwiY3JlYXRlZCI6IjIwMjEtMDMtMjJUMTI6NTE6MjYuMTI5WiIsImV4cGlyeSI6IjIwMjItMDMtMjJUMTI6NTE6MjYuMTI5WiJ9fQ==.Jfs9Xu3_Osqf0dSQpI766WHVG9IacWbIzcQHJrPQR1zwriwjW0v1aR6AYTDOHXfNp81O33kWK23MOf-kkC5U9Gkiq_7ca7FdHLgzLGjZ3216QigxCweOWAHzit37kvaDvXinyS3ceGvDI6tt_FldcoaByHJXTovKjsQzRYaGJmI9r8wfgBor5nQ6NCTm3v6lYA9Ae_6Rs3AR7DgMM2kEr0GAhDNja_VyrZthsrRsU5r5ELo4AlVCdzdhNCD8KzA4PPrD_KsCaKGjQak1sd0kXYx-IOr5vXJpiuhgyGdGyKVSKOejO_2TbY2oxuVGNg6aWGxv0hEiXJuChAzAI7_NmA==

This key consists of the following format:

SIGNING_PREFIX = "key"
SIGNING_DATA = "{SIGNING_PREFIX}/{BASE64_DATASET}"
BASE64_SIGNATURE = rsa_pkcs1_sign(SIGNING_DATA)

"{SIGNING_DATA}.{BASE64_SIGNATURE}"

An embedded dataset may be given during license creation via the key attribute. This dataset will be used to create the key signature, and it will be encoded for easier transfer. It can be decoded within your software and its authenticity can be verified cryptographically. The default dataset is a JSON object, as follows:

{
  "account": {
    "id": "fa4e22c6-436f-4134-b976-79df910acf69"
  },
  "product": {
    "id": "2c035cde-aa1b-47c1-bdbe-df0b29d8c5fb"
  },
  "policy": {
    "id": "6e29580f-a3eb-49e3-8820-f6e03ae9230b",
    "duration": 31556952
  },
  "user": {
    "id": "a499bb93-9902-4b52-8a04-76944ad7f660",
    "email": "[email protected]"
  },
  "license": {
    "id": "f2c65602-92a8-411f-9fef-eda0a662f9b6",
    "created": "2021-03-22T12:51:26.129Z",
    "expiry": "2022-03-22T12:51:26.129Z"
  }
}

The user property may be null depending on the license's user relationship. The license's expiry and policy's duration attributes may also be null if the license does not expire.

linkRSA_2048_PKCS1_ENCRYPT

Encrypt license keys with your account's 2048-bit RSA private key using RSA PKCS1 v1.5 padding.

S-Pg5rnVDE-7hG5Ep0RlL_6yah04aDqo9zhQR04VFurWJyq9GrQdODh90DlkzNBeFoypt6tD1_QxUecw24XqLQrhu3wRBiD4sDxWKIWX5PehyLSdGxD-U_zpZ5yVDw1Cexp9bivIWcV_Ld7Og5H56cN092iFjlctJ-HI1IPuk6W1hYxWlVGchasOshMyQdE-BLsW7PaeYqUHC5jQdo3huHX17p0GcaRMepvXzBbqjABJyUFZIwXue-ApadK2H0ActISG-zMJGF7uqpNrFCKMYISDWPAkmYSa_jZHIvR7uoTGNlaAcWwVhQDKt7XH1eVaZxZZtvQrTvoH72Mcv5-0kA==

This key consists of the following format:

BASE64_CIPHERTEXT = rsa_pkcs1_encrypt(BASE64_DATASET)

"{BASE64_CIPHERTEXT}"

An embedded dataset may be given during license creation via the key attribute. The dataset must contain no more than 245 bytes (please note this is byte length not string length). The default dataset is a JSON object, as follows:

{
  "id": "4040b22a-73df-48b5-8f90-bacacd2b6602",
  "created": "2021-03-15T19:27:50.440Z",
  "expiry": "2022-03-15T19:27:50.440Z",
  "duration": 31556952
}

The expiry and duration attributes may be null if the license does not expire.

linkRSA_2048_JWT_RS256

Encode a license claims payload into a JWT using the RS256 algorithm.

eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJjMGM4ZGMyMy03MDI1LTRmNjQtYWUwOC1iMzg4OWZlYmEwM2IiLCJpc3MiOiJodHRwczovL2tleWdlbi5zaCIsImF1ZCI6ImJmOWI1MjNmLWRkNjUtNDhhMi05NTEyLWZiNjZiYTZjMzcxNCIsInN1YiI6IjU0YjI5ODU2LWE0MjgtNGQyNy05NjY2LTliNjRlMWJmODZlZSIsImlhdCI6MTYxNTgzNzEyOCwibmJmIjoxNjE1ODM3MTI4LCJleHAiOjE2NDczNzMxMjh9.MSoZ4dqwTU0TIS_oOXMT20ViVoYDhLVn7dbOmo5Y3LAoy2DIt54jGL2PXl2G-Ov3DBSGhkp-nYbO6miigoXSPhx9okVnoyM78qbVUZVLmxcEiQ3SUrL_9oUhJul3DleQSFGvYPhGGtmK1H0xZuN5yodBY5OY6w2OJ5omOnq6hE8NdxLgZSwUb2POmtUlzUzx0kSqiG2tt1NW-j5OnGGgy1nqMDj1Cv5suoplmnCEajYd1x2w6G0Gmb9tg_iZbBkfh4tlidltK9uCiNWnHvsg3S-X3biSWQeRXP-2_BRdGAyrI5cvwZbWHPr8QdSsHTnOqUwCQ22A5YTEAGiSYp9lvQ

A custom JWT claims payload may be given during license creation via the key attribute. The default claims are as follows:

{
  "jti": "c0c8dc23-7025-4f64-ae08-b3889feba03b",
  "iss": "https://keygen.sh",
  "aud": "bf9b523f-dd65-48a2-9512-fb66ba6c3714",
  "sub": "54b29856-a428-4d27-9666-9b64e1bf86ee",
  "iat": 1615837128,
  "nbf": 1615837128,
  "exp": 1647373128
}

Where aud is the account ID and sub is the license ID. The exp attribute may be omitted if the license does not expire.

linkRSA_2048_PKCS1_PSS_SIGN

Deprecated: use 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.

eyJhY2NvdW50Ijp7ImlkIjoiZmE0ZTIyYzYtNDM2Zi00MTM0LWI5NzYtNzlkZjkxMGFjZjY5In0sInByb2R1Y3QiOnsiaWQiOiIyYzAzNWNkZS1hYTFiLTQ3YzEtYmRiZS1kZjBiMjlkOGM1ZmIifSwicG9saWN5Ijp7ImlkIjoiNmUyOTU4MGYtYTNlYi00OWUzLTg4MjAtZjZlMDNhZTkyMzBiIiwiZHVyYXRpb24iOjMxNTU2OTUyfSwidXNlciI6eyJpZCI6ImE0OTliYjkzLTk5MDItNGI1Mi04YTA0LTc2OTQ0YWQ3ZjY2MCIsImVtYWlsIjoidXNlckBrZXlnZW4uZXhhbXBsZSJ9LCJsaWNlbnNlIjp7ImlkIjoiOGIwZmU2MGQtMGJjOS00Zjk4LWEwNDctZTZmOGNhMWQyNThjIiwiY3JlYXRlZCI6IjIwMjEtMDMtMjJUMTI6NTI6NTAuNjgyWiIsImV4cGlyeSI6IjIwMjItMDMtMjJUMTI6NTI6NTAuNjgyWiJ9fQ==.l2ZyC7Hc-0XrEtkhldI5c1tsLt_AY8eeW96PdeR1C3Z8F6X7xrdtXBum5UDCR2dIEf552eJY91l3cVwmFVvLTqNUWGFRDzoKHVH8w2ddwocWXSHRevBLCbfj6BLMLxBCFZOiCxQdEsoA93JcsuZmijwvphG3s26F3u5MRz5wIciE6Q4a9adKnCBhcPYP4B_ZfUwXmImMsTkqlP7x5jr8yIViFSFkEiiH4tp_xQySWtMpKBuV18LWq07KrIorHT8mrSET7EzHUNRrbE7x9J2lol5-aR8A2-7_rmM042sqvhS6EQOYqxTigPpAWILK8pT3AqnJ8o2WnZI-bks8Lbc3Mg==

This key consists of the following format:

BASE64_SIGNATURE = rsa_pkcs1_pss_sign(BASE64_DATASET)

"{BASE64_DATASET}.{BASE64_SIGNATURE}"

An embedded dataset may be given during license creation via the key attribute. The default dataset is a JSON object, as follows:

{
  "account": {
    "id": "fa4e22c6-436f-4134-b976-79df910acf69"
  },
  "product": {
    "id": "2c035cde-aa1b-47c1-bdbe-df0b29d8c5fb"
  },
  "policy": {
    "id": "6e29580f-a3eb-49e3-8820-f6e03ae9230b",
    "duration": 31556952
  },
  "user": {
    "id": "a499bb93-9902-4b52-8a04-76944ad7f660",
    "email": "[email protected]"
  },
  "license": {
    "id": "8b0fe60d-0bc9-4f98-a047-e6f8ca1d258c",
    "created": "2021-03-22T12:52:50.682Z",
    "expiry": "2022-03-22T12:52:50.682Z"
  }
}

The user property may be null depending on the license's user relationship. The license's expiry and policy's duration attributes may also be null if the license does not expire.

linkRSA_2048_PKCS1_SIGN

Deprecated: use 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.

Here is an example of a cryptographically signed key using RSA_2048_PKCS1_PSS_SIGN:

eyJhY2NvdW50Ijp7ImlkIjoiZmE0ZTIyYzYtNDM2Zi00MTM0LWI5NzYtNzlkZjkxMGFjZjY5In0sInByb2R1Y3QiOnsiaWQiOiIyYzAzNWNkZS1hYTFiLTQ3YzEtYmRiZS1kZjBiMjlkOGM1ZmIifSwicG9saWN5Ijp7ImlkIjoiNmUyOTU4MGYtYTNlYi00OWUzLTg4MjAtZjZlMDNhZTkyMzBiIiwiZHVyYXRpb24iOjMxNTU2OTUyfSwidXNlciI6eyJpZCI6ImE0OTliYjkzLTk5MDItNGI1Mi04YTA0LTc2OTQ0YWQ3ZjY2MCIsImVtYWlsIjoidXNlckBrZXlnZW4uZXhhbXBsZSJ9LCJsaWNlbnNlIjp7ImlkIjoiZTI2NDdkMzAtYmYyOS00N2U0LTliYjktZWU4NzRmNDI2YjI2IiwiY3JlYXRlZCI6IjIwMjEtMDMtMjJUMTI6NTM6MjAuNDE0WiIsImV4cGlyeSI6IjIwMjItMDMtMjJUMTI6NTM6MjAuNDE0WiJ9fQ==.QmWjSqJ8yfvTcf3T0sKWUXrImaFudHVR8_WLatIVNfAciJW7__70RtOyZ2ZnN4WvyDEb37Df-hal5-zKugrS9a9OCXP_NbNusQALdSqigQH-Jkekd_X0Xnp6F2v6z9SQVgrt2_kMxQ9m2WzFXVn6R_SfW-ey_aGcX3JW7th8CsX5rGr93sb7DjR7-femwS-rGLy_t3cyqf-kYP6XX0krv4BUJi5vYcEC9MnTNDkoTervk6nczAjQhybJmD5aah2c9opbRT4R0k0wCosEYkNrsdnmj1uB2AshcmpmhemnmTxjmNvKvYO3gfgGbfIDSXSzRQhzErVwN_wLr1XANmzQYQ==

This key consists of the following format:

BASE64_SIGNATURE = rsa_pkcs1_sign(BASE64_DATASET)

"{BASE64_DATASET}.{BASE64_SIGNATURE}"

An embedded dataset may be given during license creation via the key attribute. The default dataset is a JSON object, as follows:

{
  "account": {
    "id": "fa4e22c6-436f-4134-b976-79df910acf69"
  },
  "product": {
    "id": "2c035cde-aa1b-47c1-bdbe-df0b29d8c5fb"
  },
  "policy": {
    "id": "6e29580f-a3eb-49e3-8820-f6e03ae9230b",
    "duration": 31556952
  },
  "user": {
    "id": "a499bb93-9902-4b52-8a04-76944ad7f660",
    "email": "[email protected]"
  },
  "license": {
    "id": "e2647d30-bf29-47e4-9bb9-ee874f426b26",
    "created": "2021-03-22T12:53:20.414Z",
    "expiry": "2022-03-22T12:53:20.414Z"
  }
}

The user property may be null depending on the license's user relationship. The license's expiry and policy's duration attributes may also be null if the license does not expire.

linkSignatures

You may utilize your account's public key to verify that successful requests, and webhooks, originated from Keygen, as well as to verify a license key is authentic i.e. that it was signed using your Keygen account's private key.

You can find your account's public key within your dashboard settings page, which you can use to verify response payloads and license keys. Private keys are kept securely encrypted on our servers and are never, under any circumstances, shared with you or any other third-party.

linkLicense Signatures

License signature verification is useful for checking if a given license key is authentic, especially in offline environments, where access to Keygen's API to fully validate the license is not available. For more information on license key cryptography and signatures, see the info below, view the cryptography section and review the various policy schemes available.

Here are a few examples of cryptographically verifying a license's authenticity:

The signed or encrypted contents of the key are base64url encoded using RFC 4648, a URL-safe version of base64 which is supported in most programming languages. This base64url encoding scheme is different than normal base64 encoding. Most programming languages will have a separate function for decoding URL base64 encoded values, but if not, you can simply replace all "-" base64 chars with "+", and replace "_" with "/", e.g. tr '-_' '+/'.

Example RSA_2048_PKCS1_SIGN_V2 verification using Python

from Crypto.PublicKey import RSA
from Crypto.Signature import PKCS1_v1_5
from Crypto.Hash import SHA256
import base64

# This should be replaced with your Keygen account's public key (note: all newlines and whitespace must be *exact*)
PUBLIC_KEY = \
"""-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzPAseDYupK78ZUaSbGw7
YyUCCeKo/1XqTACOcmTTHHGgeHacLK2j9UrbTlhW5h8Vyo0iUEHrY1Kgf4wwiGgF
h0Yc+oDWDhq1bIertI03AE420LbpUf6OTioX+nY0EInxXF3J7aAdx/R/nYgRJrLZ
9ATWaQVSgf3vtxCtCwUeKxKZI41GA/9KHTcCmd3BryAQ1piYPr+qrEGf2NDJgr3W
vVrMtnjeoordAaCTyYKtfm56WGXeXr43dfdejBuIkI5kqSzwVyoxhnjE/Rj6xks8
ffH+dkAPNwm0IpxXJerybjmPWyv7iyXEUN8CKG+6430D7NoYHp/c991ZHQBUs59g
vwIDAQAB
-----END PUBLIC KEY-----"""

# This should be the license key that you're cryptographically verifying
LICENSE_KEY = \
"""key/eyJhY2NvdW50Ijp7ImlkIjoiYmY5YjUyM2YtZGQ2NS00OGEyLTk1MTItZmI2NmJhNmMzNzE0In0sInByb2R1Y3QiOnsiaWQiOiI5NTYxYzdkMC1mYzczLTRjOTQtYTZlZC0xY2M3MmEzZTAzNzYifSwicG9saWN5Ijp7ImlkIjoiOTRiYTA5YjYtMzI5ZC00NWNjLTg4ZjctNzM5N2Y2YzgwNDg4In0sInVzZXIiOnsiaWQiOiIxYmEwYzk4Yy0wMGRhLTQ2MjEtOTljNS1jMWU1ZjVkZjk1NzUiLCJlbWFpbCI6InVzZXJAYXBwLmV4YW1wbGUifSwibGljZW5zZSI6eyJpZCI6IjE2YmI3YmM2LTBlNDItNDYyZS04OWE1LWVmNzdjNDYwNzJjYiIsImNyZWF0ZWQiOiIyMDIxLTAzLTE2VDEzOjE4OjE3LjU1M1oiLCJleHBpcnkiOiIyMDIyLTAzLTE2VDEzOjE4OjE3LjU1M1oifX0=.K0VwYlN3LVdRniqL5lpDDqticp1-LhmW-WEyRmK7rhGHFhBMThHMp1qjzpdSHaV4bKpTFQgnmj5p-Bw7n9nKnYZ35kmc_2bnid-69q0G6sA2iXEtS3I5717cLArN7HL5l-lBTYZwSTbq_C_NnnpvxQ2k8aMSOwP9ZkV8SECee9VOEniDD7URZIYMf06JVzSsfprAaEcXEGaSK_LXw5y0cy0o9hcmPC50JdWPPxQtj13DKt0Yc_0CkyHvVfZO8h_hdRf5JSCW9UZumUrHk_wqQf3j-DBfmOytKTidmsIaQqE2KyoJh_-U1T1z4fx44wYDFTLEncr4uWX3zzUTf_cVIA=="""

# Split license key to obtain signing data and signature, then parse data
# and decode base64url encoded values
signing_data, enc_sig = LICENSE_KEY.split(".")
signing_prefix, enc_key = signing_data.split("/")

key = base64.urlsafe_b64decode(enc_key)
sig = base64.urlsafe_b64decode(enc_sig)

# Verify the key's signature
pub_key = RSA.importKey(PUBLIC_KEY)
verifier = PKCS1_v1_5.new(pub_key)
digest = SHA256.new(data="key/" + enc_key)

print(
  verifier.verify(digest, sig)
)

linkRequest Signatures

Request signature verification is useful for verifying requests came from Keygen, for verifying the authenticity of cached data in offline environments, as well as for preventing man-in-the-middle (MITM) attacks, where an attacker will redirect requests to a local server under their control which defaults to sending "valid" license responses.

A signature header will always be included with webhook events delivered to your webhook endpoints.

We do not sign certain error payloads - please keep this in mind during implementation. We will always sign successful responses (2xx–3xx) and errors that occur while authenticated using your account's private key. Certain error responses, such as authentication errors, will not include the X-Signature header.

Code examples for verifying request signatures:

Header Description
X-Signature The base64 encoded RSA-SHA256 signature of the response body, using PKCS1 v1.5 padding.

To see an example of signature verfication, check out our example on GitHub. It will show you how to utilize your account's public key to verify that the response was signed using your account's private key.

Example request signature

X-Signature: fUKlYwejbSxKGtWfqcx5SfeHlhw16c+5tb0JluFwkIOCyzcUug+F1vNMFiKg03Zs/wwS1UKNEdI9Cx8EvFUn/7XFuaNL5AqAPdjdBt5kW3D1wqFtDPSGjh4lmRNybn158yM3cZJOQcg1tCHjWjzSYERELZyTbS+gjLr8mnrcTiAl+vZr4AJkxzdT0NrK633oTwzcsk2564BRh96YqSsmbMhPKl9R8r3Ulqe23bvl0h5vCHwlspzm9dpywnvc+He+imFj6Cxuz9FXnlXx6SxXzwcfWEJPa1CPtZPLy8gIlHNL195lr5s1wPsMv1jz5bp8adWOFKA9Ed7ocODZYU/fgg==
{
  "data": {
    …
  }
}

linkTesting

When implementing a testing strategy for your licensing integration, we recommend that you fully mock our APIs. This is especially important for CI/CD systems, to prevent unneeded load on our servers. Mocking our APIs will also allow you to more easily stay within your account's daily request limits.

Most popular programming languages will have at least 1 mocking library for HTTP APIs, but feel free to reach out to us for recommendations.

linkSandbox

A sandbox environment is coming soon. If you're in need of a sandbox account, please reach out.

linkTokens

linkThe token object

Keygen authenticates your API requests using tokens. Below you will find the various attributes for the token resource, as well as the token resource's relationships. The actual token string is hashed before being stored in our databases, thus is only available directly after generating/regenerating a token. Tokens with an expiry will automatically be deleted 90 days after their expiry, unless renewed.

Admin and product tokens should not be included in any client-facing code, as they offer full access to all of your account's resources. You can authenticate as one of your users or use an activation token to perform client-side machine activations. Admin and product tokens should only be used server-side.

linkAttributes

  • linkkind

    stringread only

    The kind of token, based on its bearer.

    Options

    • activation-token: An activation token with permission to activate and deactivate the machines for a given license.
    • product-token: An internal administrative token with permission to manage the entire product and its resources, usually for server-side use.
    • user-token: A normal user of one or more of your products, with limited permission to manage their own resources.
    • support-token: An internal administrative user of your Keygen account, with a limited subset of permissions.
    • sales-token: An internal administrative user of your Keygen account, with a limited subset of permissions.
    • developer-token: An internal administrative user of your Keygen account, with permission to manage most resources.
    • admin-token: An internal administrative user of your Keygen account, with permission to manage the entire account.

  • linktoken

    stringread only

    The raw token of the token. This attribute is only available to read directly after token generation. This is the value you will use to authenticate with when sending requests to our API.

  • linkexpiry

    timestamp (ISO8601 format)read only

    The timestamp for when the token expires. Requests using an expired token will be rejected.

  • linkmaxActivations

    integer

    The maximum amount of machine activations this token may perform. This attribute is only applicable to activation tokens.

  • linkactivations

    integerread only

    The number of machine activations that have been performed by this token. This attribute is only applicable to activation tokens.

  • linkmaxDeactivations

    integer

    The maximum amount of machine deactivations this token may perform. This attribute is only applicable to activation tokens.

  • linkdeactivations

    integerread only

    The number of machine deactivations that have been performed by this token. This attribute is only applicable to activation tokens.

  • linkcreated

    timestamp (ISO8601 format)read only

    When the token was created.

  • linkupdated

    timestamp (ISO8601 format)read only

    When the token was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the token belongs to.

  • linkbearer

    individual

    The bearer of the token.

Example object

{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "kind": "user-token",
      "token": "user-57c1cdc2a084f0ebd46850e5742b1f0bca47d1ca5f5262f6c5969fec8dbd530dv3",
      "expiry": "<%= expiry %>",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}

linkGenerate a token

Generate a new token resource for a user. To generate a token for a product, see the product token relationship. To generate an activation token, see the license token relationship. By default, user tokens expire in 2 weeks, and admin tokens do not expire. A custom expiry may be provided in the token generate request.

Admin and product tokens should not be included in any client-facing code, as they offer full access to all of your account's resources. You can authenticate as one of your users or use an activation token to perform client-side machine activations. Admin and product tokens should only be used server-side.

linkAuthentication

  • linkBasic

    required

    The email and password of the user. Credentials MUST use a colon (i.e. ":") to separate the email and password (i.e. "EMAIL:PASSWORD"), and those credentials MUST then be base64 encoded.

linkParameters

  • linkaccount

    string, required

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

linkAttributes

  • linkexpiry

    timestamp (ISO8601 format), optional

    The timestamp for when the token expires. Requests using an expired token will be rejected.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const credentials = new Buffer("<%= email %>:<%= password %>").toString("base64")
const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/tokens", {
  method: "POST",
  headers: {
    "Accept": "application/vnd.api+json",
    "Authorization": `Basic ${credentials}`
  }
})

const { data, errors } = await response.json()
import requests
import json

res = requests.post(
  "https://api.keygen.sh/v1/accounts/<%= account %>/tokens",
  headers={ "Accept": "application/vnd.api+json" },
  auth=("<%= email %>", "<%= password %>")
).json()
import SwiftyJSON
import Alamofire

let credentials = Data("<%= email %>:<%= password %>".utf8).base64EncodedString()

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/tokens",
  method: .post,
  headers: [
    "Accept": "application/vnd.api+json",
    "Authorization": "Basic \(credentials)"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
using RestSharp;
using System;
using System.Text;

var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes("<%= email %>:<%= password %>"));

var client = new RestClient("https://api.keygen.sh/v1/accounts/<%= account %>");
var request = new RestRequest("tokens", Method.POST);

request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", $"Basic {credentials}");

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 %>/tokens")
  .header("Accept", "application/vnd.api+json")
  .basicAuth("<%= email %>", "<%= password %>")
  .asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;

HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/tokens")
  .header("Accept", "application/vnd.api+json")
  .basicAuth("<%= email %>", "<%= password %>")
  .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_config config;
credentials cred("<%= email %>", "<%= password %>");
config.set_credentials(cred);

http_client client("https://api.keygen.sh/v1/accounts/<%= account %>", config);
http_request req;

req.headers().add("Accept", "application/json");

req.set_request_uri("/tokens");
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 %>/tokens \
  -H 'Accept: application/vnd.api+json' \
  -u "<%= email %>:<%= password %>"

Example response / 201 Created

{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "kind": "user-token",
      "token": "user-f4869386e3b6b39d1f42949131f97a39b42f9a74c553ba7244bbed9d1f79f106v3",
      "expiry": "<%= expiry %>",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}

linkRetrieve a token

Retrieves the details of an existing token.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resource: either an admin or the token owner.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the token to be retrieved.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa", {
  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 %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  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(
  "tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  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 %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .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 %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .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("/tokens/6a7562be-b302-43d2-a550-30d6026247aa");
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 %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "kind": "admin-token",
      "expiry": "<%= expiry %>",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}

linkRegenerate a token

Regenerate an existing token resource. This will replace the token attribute with a new secure token, and extend the token's expiry by 2 weeks from the current time.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the token owner.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, optional

    The identifier (UUID) of the token to be regenerated. If ommited, the token used to authenticate will be regenerated.

linkReturns

A 200 OK response will be returned along with the regenerated token object.

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa", {
  method: "PUT",
  headers: {
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})

const { data, errors } = await response.json()
import requests
import json

res = requests.put(
  "https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  method: .put,
  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(
  "tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  Method.PUT
);

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.put("https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .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.put("https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .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("/tokens/6a7562be-b302-43d2-a550-30d6026247aa");
req.set_method(methods::PUT);

client.request(req)
  .then([](http_response res) {
    auto data = res.extract_json().get();
  })
  .wait();
curl -X PUT https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "6a7562be-b302-43d2-a550-30d6026247aa",
    "type": "tokens",
    "attributes": {
      "kind": "user-token",
      "token": "user-72abcf7e9bce107df746fab6751f875aad7801d8edc7b9b9afb2f97ee53b59e7v3",
      "expiry": "<%= expiry %>",
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        },
        "data": {
          "type": "users",
          "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
        }
      }
    }
  }
}

linkRevoke a token

Permanently revokes a token. It cannot be undone. This action also immediately invalidates all sessions using the given token.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the token owner.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the token to be revoked.

linkReturns

A 204 No Content response will be returned.

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa", {
  method: "DELETE",
  headers: {
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import requests

res = requests.delete(
  "https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
)
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  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(
  "tokens/6a7562be-b302-43d2-a550-30d6026247aa",
  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 %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .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 %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa")
  .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("/tokens/6a7562be-b302-43d2-a550-30d6026247aa");
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 %>/tokens/6a7562be-b302-43d2-a550-30d6026247aa \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkList all tokens

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

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resources.

linkParameters

  • linkaccount

    string, required

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

linkFilters

  • linklimit

    integer, default is10

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

    https://api.keygen.sh/v1/accounts/<%= account %>/tokens?limit=25

  • linkpage

    hash<string, integer>

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

    https://api.keygen.sh/v1/accounts/<%= account %>/tokens?page[size]=15&page[number]=2

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/tokens?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 %>/tokens?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 %>/tokens?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("tokens", 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 %>/tokens")
  .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 %>/tokens")
  .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("/tokens");
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 %>/tokens?limit=15 -g \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": [
    {
      "id": "6a7562be-b302-43d2-a550-30d6026247aa",
      "type": "tokens",
      "attributes": {
        "kind": "admin-token",
        "expiry": "<%= expiry %>",
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        },
        "bearer": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298"
          },
          "data": {
            "type": "users",
            "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298"
          }
        }
      }
    },
    …
  ]
}

linkProducts

linkThe product object

Below you will find the various attributes for the product resource, as well as the product resource's relationships.

linkAttributes

  • linkname

    string

    The name of the product.

  • linkurl

    string

    A related URL for the product e.g. the marketing website, company website, etc.

  • linkplatforms

    array<string>

    An array of platforms the product supports.

  • linkmetadata

    hash<string, scalar>

    Hash containing product metadata.

  • linkcreated

    timestamp (ISO8601 format)read only

    When the product was created.

  • linkupdated

    timestamp (ISO8601 format)read only

    When the product was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the product belongs to.

  • linkpolicies

    collection

    The policies that are associated with the product.

  • linklicenses

    collection

    The licenses that are associated with the product.

  • linkmachines

    collection

    The machines that are associated with the product.

  • linkusers

    collection

    The users that own a license for the product.

  • linktokens

    collection

    The authentication tokens of the product.

Example object

{
  "data": {
    "id": "31339351-f7f5-4bdd-8346-5d8399a1ac07",
    "type": "products",
    "links": {
      "self": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07"
    },
    "attributes": {
      "name": "Product Hunt",
      "url": "https://producthunt.com",
      "platforms": ["iOS", "Android"],
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "policies": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/policies"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/machines"
        }
      },
      "users": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/users"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens"
        }
      }
    }
  }
}

linkCreate a product

Creates a new product resource.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

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

linkAttributes

  • linkname

    string, required

    The name of the product.

  • linkurl

    string, optional

    A related URL for the product e.g. the marketing website, company website, etc. Must be a valid URL.

  • linkplatforms

    array<string>, optional

    An array of platforms the product supports.

  • linkmetadata

    hash<string, scalar>, optional

    Hash containing product metadata.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/products", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "products",
      "attributes": {
        "name": "Product Hunt",
        "url": "https://producthunt.com",
        "platforms": ["iOS", "Android"]
      }
    }
  })
})

const { data, errors } = await response.json()
import requests
import json

res = requests.post(
  "https://api.keygen.sh/v1/accounts/<%= account %>/products",
  headers={
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  data=json.dumps({
    "data": {
      "type": "products",
      "attributes": {
        "name": "Product Hunt",
        "url": "https://producthunt.com",
        "platforms": ["iOS", "Android"]
      }
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/products",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "products",
      "attributes": [
        "name": "Product Hunt",
        "url": "https://producthunt.com",
        "platforms": ["iOS", "Android"]
      ]
    ]
  ],
  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("products", 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 = "products",
    attributes = new {
      name = "Product Hunt",
      url = "https://producthunt.com",
      platforms = new[] { "iOS", "Android" }
    }
  }
});

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 "products",
    "attributes" to mapOf(
      "name" to "Product Hunt",
      "url" to "https://producthunt.com",
      "platforms" to listOf("iOS", "Android")
    )
  )
))

val res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/products")
  .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", ofEntries(
    entry("type", "products"),
    entry("attributes", ofEntries(
      entry("name", "Product Hunt"),
      entry("url", "https://producthunt.com"),
      entry("platforms", of("iOS", "Android"))
    ))
  ))
));

HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/products")
  .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 platforms;
platforms[0] = value::string("iOS");
platforms[1] = value::string("Android");

value attrs;
attrs["name"] = value::string("Product Hunt");
attrs["url"] = value::string("https://producthunt.com");
attrs["platforms"] = platforms;

value data;
data["type"] = value::string("products");
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("/products");
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 %>/products \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "products",
          "attributes": {
            "name": "Product Hunt",
            "url": "https://producthunt.com",
            "platforms": ["iOS", "Android"]
          }
        }
      }'

Example response / 201 Created

{
  "data": {
    "id": "31339351-f7f5-4bdd-8346-5d8399a1ac07",
    "type": "products",
    "links": {
      "self": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07"
    },
    "attributes": {
      "name": "Product Hunt",
      "url": "https://producthunt.com",
      "platforms": ["iOS", "Android"],
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "policies": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/policies"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/machines"
        }
      },
      "users": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/users"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens"
        }
      }
    }
  }
}

linkRetrieve a product

Retrieves the details of an existing product.

linkAuthentication

  • linkBearer

    required

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

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the product to be retrieved.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07", {
  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 %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07",
  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(
  "products/31339351-f7f5-4bdd-8346-5d8399a1ac07",
  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 %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07")
  .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 %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07")
  .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("/products/31339351-f7f5-4bdd-8346-5d8399a1ac07");
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 %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07 \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "31339351-f7f5-4bdd-8346-5d8399a1ac07",
    "type": "products",
    "links": {
      "self": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07"
    },
    "attributes": {
      "name": "Product Hunt",
      "url": "https://producthunt.com",
      "platforms": ["iOS", "Android"],
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "policies": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/policies"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/machines"
        }
      },
      "users": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/users"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens"
        }
      }
    }
  }
}

linkUpdate a product

Updates the specified product 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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the product to be updated.

linkAttributes

  • linkname

    string, optional

    The name of the product.

  • linkurl

    string, optional

    A related URL for the product e.g. the marketing website, company website, etc. Must be a valid URL.

  • linkplatforms

    array<string>, optional

    An array of platforms the product supports.

  • linkmetadata

    hash<string, scalar>, optional

    Hash containing product metadata.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "products",
      "attributes": {
        "platforms": [
          "iOS",
          "Android",
          "Windows"
        ]
      }
    }
  })
})

const { data, errors } = await response.json()
import requests
import json

res = requests.patch(
  "https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07",
  headers={
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  data=json.dumps({
    "data": {
      "type": "products",
      "attributes": {
        "platforms": [
          "iOS",
          "Android",
          "Windows"
        ]
      }
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07",
  method: .patch,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "products",
      "attributes": [
        "platforms": [
          "iOS",
          "Android",
          "Windows"
        ]
      ]
    ]
  ],
  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(
  "products/31339351-f7f5-4bdd-8346-5d8399a1ac07",
  Method.PATCH
);

request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer <%= token %>");

request.AddJsonBody(new {
  data = new {
    type = "products",
    attributes = new {
      platforms = new[] { "iOS", "Android", "Windows" }
    }
  }
});

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 "products",
    "attributes" to mapOf(
      "platforms" to listOf("iOS", "Android", "Windows")
    )
  )
))

val res = Unirest.patch("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07")
  .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", ofEntries(
    entry("type", "products"),
    entry("attributes", ofEntries(
      entry("platforms", of("iOS", "Android", "Windows"))
    ))
  ))
));

HttpResponse<JsonNode> res = Unirest.patch("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07")
  .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 platforms;
platforms[0] = value::string("iOS");
platforms[1] = value::string("Android");
platforms[2] = value::string("Windows");

value attrs;
attrs["platforms"] = platforms;

value data;
data["type"] = value::string("products");
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("/products/31339351-f7f5-4bdd-8346-5d8399a1ac07");
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 %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "products",
          "attributes": {
            "platforms": [
              "iOS",
              "Android",
              "Windows"
            ]
          }
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "31339351-f7f5-4bdd-8346-5d8399a1ac07",
    "type": "products",
    "links": {
      "self": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07"
    },
    "attributes": {
      "name": "Product Hunt",
      "url": "https://producthunt.com",
      "platforms": ["iOS", "Android", "Windows"],
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "policies": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/policies"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/machines"
        }
      },
      "users": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/users"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens"
        }
      }
    }
  }
}

linkDelete a product

Permanently deletes a product. It cannot be undone. This action also immediately deletes any policies, licenses and machines that the product is associated with.

linkAuthentication

  • linkBearer

    required

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

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the product to be deleted.

linkReturns

A 204 No Content response will be returned.

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07", {
  method: "DELETE",
  headers: {
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import requests

res = requests.delete(
  "https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
)
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07",
  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(
  "products/31339351-f7f5-4bdd-8346-5d8399a1ac07",
  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 %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07")
  .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 %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07")
  .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("/products/31339351-f7f5-4bdd-8346-5d8399a1ac07");
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 %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07 \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkList all products

Returns a list of products. The products are returned sorted by creation date, with the most recent products appearing first.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

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

linkFilters

  • linklimit

    integer, default is10

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

    https://api.keygen.sh/v1/accounts/<%= account %>/products?limit=25

  • linkpage

    hash<string, integer>

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

    https://api.keygen.sh/v1/accounts/<%= account %>/products?page[size]=15&page[number]=2

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/products?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 %>/products?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 %>/products?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("products", 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 %>/products")
  .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 %>/products")
  .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("/products");
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 %>/products?limit=15 -g \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": [
    {
      "id": "31339351-f7f5-4bdd-8346-5d8399a1ac07",
      "type": "products",
      "links": {
        "self": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07"
      },
      "attributes": {
        "name": "Product Hunt",
        "url": "https://producthunt.com",
        "platforms": ["iOS", "Android"],
        "metadata": {},
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        },
        "policies": {
          "links": {
            "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/policies"
          }
        },
        "licenses": {
          "links": {
            "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/licenses"
          }
        },
        "machines": {
          "links": {
            "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/machines"
          }
        },
        "users": {
          "links": {
            "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/users"
          }
        },
        "tokens": {
          "links": {
            "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens"
          }
        }
      }
    },
    …
  ]
}

linkGenerate a product token

Generates a new product token resource. Product tokens do not expire.

Product tokens should not be included in any client-facing code, as they offer full access to all of the product's resources. Only use these tokens server-side e.g. to consume webhooks or to create new resources in response to events from your payment provider.

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the product to generate a token for.

linkReturns

A 200 OK response will be returned along with the new token object.

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens", {
  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 %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens",
  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(
  "products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens",
  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 %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens")
  .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 %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens")
  .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("/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens");
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 %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07/tokens \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "07d52aa8-b96c-4b55-b05d-f5f570e1775a",
    "type": "tokens",
    "attributes": {
      "kind": "product-token",
      "token": "prod-2ddd064509b6bcaa356958dcce6da3a538919e13ddbc26b359fb374ff89dfacav3",
      "expiry": "<%= expiry %>",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<%= account %>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07"
        },
        "data": {
          "type": "products",
          "id": "31339351-f7f5-4bdd-8346-5d8399a1ac07"
        }
      }
    }
  }
}

linkEntitlements

linkThe entitlement object

Below you will find the various attributes for the entitlement resource. Entitlements can be attached to policies and to licenses to grant named "permissions" for things such as application features.

Entitlements can be attached to the following resources:

  • Policies: Any entitlement attached to a policy will automatically be attached to all licenses which implement the given policy.
  • Licenses: Entitlements attached to a license are one-off and only apply to that specific license resource.

linkAttributes

  • linkname

    string

    The name of the entitlement.

  • linkcode

    string

    The unique code for the entitlement. This can be used within license validation requests to assert a license possesses a given entitlement.

  • linkcreated

    timestamp (ISO8601 format)read only

    When the entitlement was created.

  • linkupdated

    timestamp (ISO8601 format)read only

    When the entitlement was last updated.

  • linkmetadata

    hash<string, scalar>

    Hash containing entitlement metadata.

linkRelationships

  • linkaccount

    individual

    The account that the entitlement belongs to.

Example object

{
  "data": {
    "id": "db1ff21b-f42f-4623-952b-ca7f2600bded",
    "type": "entitlements",
    "attributes": {
      "name": "Example Feature",
      "code": "EXAMPLE_FEATURE",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      }
    },
    "links": {
      "self": "/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded"
    }
  }
}

linkCreate an entitlement

Creates a new entitlement resource.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to create the resource: an admin.

linkParameters

  • linkaccount

    string, required

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

linkAttributes

  • linkname

    string, required

    The name of the entitlement.

  • linkcode

    string, required

    The unique code for the entitlement. The code cannot collide with any entitlements that already exist.

  • linkmetadata

    hash<string, scalar>, optional

    Hash containing entitlement metadata.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/entitlements", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "entitlements",
      "attributes": {
        "name": "Example Entitlement",
        "code": "EXAMPLE_ENTITLEMENT"
      }
    }
  })
})

const { data, errors } = await response.json()
import requests
import json

res = requests.post(
  "https://api.keygen.sh/v1/accounts/<%= account %>/entitlements",
  headers={
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  data=json.dumps({
    "data": {
      "type": "entitlements",
      "attributes": {
        "name": "Example Entitlement",
        "code": "EXAMPLE_ENTITLEMENT"
      }
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/entitlements",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "entitlements",
      "attributes": [
        "name": "Example Entitlement",
        "code": "EXAMPLE_ENTITLEMENT"
      ]
    ]
  ],
  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("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",
    attributes = new {
      name = "Example Entitlement",
      code = "EXAMPLE_ENTITLEMENT"
    }
  }
});

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 "entitlements",
    "attributes" to mapOf(
      "name" to "Example Entitlement",
      "code" to "EXAMPLE_ENTITLEMENT"
    )
  )
))

val res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/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;

JSONObject body = new JSONObject(ofEntries(
  entry("data", ofEntries(
    entry("type", "entitlements"),
    entry("attributes", ofEntries(
      entry("name", "Example Entitlement"),
      entry("code", "EXAMPLE_ENTITLEMENT")
    ))
  ))
));

HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/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 attrs;
attrs["name"] = value::string("Example Entitlement");
attrs["code"] = value::string("EXAMPLE_ENTITLEMENT");

value data;
data["type"] = value::string("entitlements");
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("/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 %>/entitlements \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "entitlements",
          "attributes": {
            "name": "Example Feature",
             "code": "EXAMPLE_FEATURE",
          }
        }
      }'

Example response / 201 Created

{
  "data": {
    "id": "db1ff21b-f42f-4623-952b-ca7f2600bded",
    "type": "entitlements",
    "attributes": {
      "name": "Example Feature",
      "code": "EXAMPLE_FEATURE",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      }
    },
    "links": {
      "self": "/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded"
    }
  }
}

linkRetrieve an entitlement

Retrieves the details of an existing entitlement.

linkAuthentication

  • linkBearer

    required

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

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the entitlement to be retrieved.

linkReturns

A 200 OK response will be returned along with an entitlement object.

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded", {
  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 %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded",
  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/db1ff21b-f42f-4623-952b-ca7f2600bded",
  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 %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded")
  .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 %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded")
  .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("/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded");
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 %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded \
  -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": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      }
    },
    "links": {
      "self": "/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded"
    }
  }
}

linkUpdate an entitlement

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

Renaming an entitlement code that is already in use may cause license validations using the old entitlement code to fail. We suggest making sure the existing code is no longer in use before changing it, to prevent unintented license validation failures.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: an admin.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the entitlement to be updated.

linkAttributes

  • linkname

    string, optional

    The name of the entitlement.

  • linkcode

    string, optional

    The unique code for the entitlement.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "entitlements",
      "attributes": {
        "code": "EXAMPLE_ENTITLEMENT_CODE"
      }
    }
  })
})

const { data, errors } = await response.json()
import requests
import json

res = requests.patch(
  "https://api.keygen.sh/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded",
  headers={
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  data=json.dumps({
    "data": {
      "type": "entitlements",
      "attributes": {
        "code": "EXAMPLE_ENTITLEMENT_CODE"
      }
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded",
  method: .patch,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "entitlements",
      "attributes": [
        "code": "EXAMPLE_ENTITLEMENT_CODE"
      ]
    ]
  ],
  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(
  "entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded",
  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 = "entitlements",
    attributes = new {
      code = "EXAMPLE_ENTITLEMENT_CODE"
    }
  }
});

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 "entitlements",
    "attributes" to mapOf(
      "code" to "EXAMPLE_ENTITLEMENT_CODE"
    )
  )
))

val res = Unirest.patch("https://api.keygen.sh/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded")
  .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", "entitlements"),
    entry("attributes", ofEntries(
      entry("code", "EXAMPLE_ENTITLEMENT_CODE")
    ))
  ))
));

HttpResponse<JsonNode> res = Unirest.patch("https://api.keygen.sh/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded")
  .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["code"] = value::string("EXAMPLE_ENTITLEMENT_CODE");

value data;
data["type"] = value::string("entitlements");
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("/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded");
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 %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "entitlements",
          "attributes": {
            "code": "EXAMPLE_ENTITLEMENT_CODE"
          }
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "db1ff21b-f42f-4623-952b-ca7f2600bded",
    "type": "entitlements",
    "attributes": {
      "name": "Example Feature",
      "code": "EXAMPLE_ENTITLEMENT_CODE",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      }
    },
    "links": {
      "self": "/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded"
    }
  }
}

linkDelete an entitlement

Permanently deletes an entitlement. The entitlement will immediately be removed from all licenses and policies. It cannot be undone.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: an admin.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the entitlement to be deleted.

linkReturns

A 204 No Content response will be returned.

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded", {
  method: "DELETE",
  headers: {
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import requests

res = requests.delete(
  "https://api.keygen.sh/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
)
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded",
  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(
  "entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded",
  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 %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded")
  .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 %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded")
  .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("/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded");
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 %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkList all entitlements

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

To list entitlements for an individual policy or license, use the given resource's scoped entitlements relationship.

linkAuthentication

  • linkBearer

    required

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

linkParameters

  • linkaccount

    string, required

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

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 %>/entitlements?limit=25

  • linkpage

    hash<string, integer>

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

    https://api.keygen.sh/v1/accounts/<%= account %>/entitlements?page[size]=15&page[number]=2

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/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 %>/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 %>/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 %>/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 %>/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("/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 %>/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": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        }
      },
      "links": {
        "self": "/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded"
      }
    },
    …
  ]
}

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.

linkAttributes

  • linkname

    string

    The name of the policy.

  • linkduration

    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.

  • linkstrict

    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.

  • linkfloating

    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.

  • linkconcurrent

    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."

  • linkscheme

    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. Requires a key to be specified at license creation i.e. these schemes are not compatible with automatic license key generation.

    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

    • 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 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.

  • linkrequireProductScope

    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).

  • linkrequirePolicyScope

    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).

  • linkrequireMachineScope

    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).

  • linkrequireFingerprintScope

    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.

  • linkrequireCheckIn

    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.

  • linkcheckInInterval

    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.

  • linkcheckInIntervalCount

    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.

  • linkusePool

    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.

  • linkmaxMachines

    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.

  • linkmaxCores

    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.

  • linkmaxUses

    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.

  • linkencrypted

    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.

  • linkprotected

    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.

  • linkheartbeatDuration

    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.

  • linkfingerprintUniquenessStrategy

    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.

  • linkfingerprintMatchingStrategy

    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.

  • linkmetadata

    hash<string, scalar>

    Hash containing policy metadata.

  • linkcreated

    timestamp (ISO8601 format)read only

    When the policy was created.

  • linkupdated

    timestamp (ISO8601 format)read only

    When the policy was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the policy belongs to.

  • linkproduct

    individual

    The product that the policy is associated with.

  • linkpool

    collection

    The pool of pre-determined keys for the policy.

  • linklicenses

    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",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

linkAttributes

  • linkname

    string, required

    The name of the policy.

  • linkduration

    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.

  • linkscheme

    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. Requires a key to be specified at license creation i.e. these schemes are not compatible with automatic license key generation.

    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

    • 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 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 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 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}.
    • RSA_2048_PKCS1_ENCRYPT: Encrypt license keys with your account's 2048-bit RSA private key using RSA PKCS1 v1.5 padding. The given license key will be encrypted using your account's private key and then base64url encoded. 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 the given license key 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 license's 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 given license key 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}.
    • 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 given license key 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}.

  • linkstrict

    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.

  • linkfloating

    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.

  • linkconcurrent

    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.

  • linkrequireProductScope

    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).

  • linkrequirePolicyScope

    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).

  • linkrequireMachineScope

    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).

  • linkrequireFingerprintScope

    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.

  • linkrequireCheckIn

    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.

  • linkcheckInInterval

    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.

  • linkcheckInIntervalCount

    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.

  • linkusePool

    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.

  • linkmaxMachines

    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.

  • linkmaxCores

    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.

  • linkmaxUses

    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.

  • linkprotected

    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.

  • linkheartbeatDuration

    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.

  • linkfingerprintUniquenessStrategy

    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.

  • linkfingerprintMatchingStrategy

    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.

  • linkmetadata

    hash<string, scalar>, optional

    Hash containing policy metadata.

linkRelationships

  • linkproduct

    linkage, required

    The product the policy is for.

linkReturns

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

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",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the policy to be retrieved.

linkReturns

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

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",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the policy to be updated.

linkAttributes

  • linkname

    string, optional

    The name of the policy.

  • linkduration

    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.

  • linkstrict

    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.

  • linkfloating

    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.

  • linkconcurrent

    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.

  • linkrequireProductScope

    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).

  • linkrequirePolicyScope

    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).

  • linkrequireMachineScope

    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).

  • linkrequireFingerprintScope

    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.

  • linkrequireCheckIn

    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.

  • linkcheckInInterval

    string, optional

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

  • linkcheckInIntervalCount

    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.

  • linkmaxMachines

    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.

  • linkmaxCores

    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.

  • linkmaxUses

    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.

  • linkprotected

    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.

  • linkheartbeatDuration

    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.

  • linkfingerprintUniquenessStrategy

    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.

  • linkfingerprintMatchingStrategy

    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.

  • linkmetadata

    hash<string, scalar>, optional

    Hash containing policy metadata.

linkReturns

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

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",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the policy to be deleted.

linkReturns

A 204 No Content response will be returned.

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.

linkParameters

  • linkaccount

    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

    hash<string, integer>

    Hash 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.

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",
        "metadata": {},
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    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.

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": "<%= created %>",
      "updated": "<%= created %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    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.

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": "<%= created %>",
        "updated": "<%= created %>"
      },
      "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    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.

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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    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

    hash<string, integer>

    Hash 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.

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": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        }
      },
      "links": {
        "self": "/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded"
      }
    },
    …
  ]
}

linkUsers

Keygen provides identity management for your customers, which allows you to authenticate them using an email/password by creating a token. The token can then be used to manage their resources in a client-side environment, e.g. activating machines, creating licenses, etc. In addition, it offers other features such as associating multiple licensing with a single user, a simple password reset flow, etc.

Not a big fan of the whole "license key" system, which requires your users to keep track of and remember long, complicated keys? Then our user identity management might be a great fit for you. It allows your users to authenticate with our API using only an email and password, something they're used to keeping track of. It can not only improve the overall user experience for your product, but it may also decrease your support costs (many of which are historically about forgotten license keys).

linkThe user object

Below you will find the various attributes for the user resource, as well as the user resource's relationships. To modify a relationship, you will need to use the canonical link for the given resource.

linkAttributes

  • linkfullName

    stringread only

    The full name of the user.

  • linkfirstName

    string

    The first name of the user.

  • linklastName

    string

    The last name of the user.

  • linkemail

    string

    The unique email of the user.

  • linkrole

    string

    The role of the user.

    For more in-depth information on user roles, and detailed resource permissions for each role, please see the roles and permissions section.

    Options

    • user: A normal user of one or more of your products. Depending on account settings, they can have permission to manage their own resources, e.g. licenses and machines. They cannot manage other users' resources.
    • support-agent: An internal administrative user of your Keygen account, with a limited subset of permissions. Support Agents can read most resource data, but cannot create, update or delete resources.
    • sales-agent: An internal administrative user of your Keygen account, with a limited subset of permissions. Sales Agents can read most resource data, but can only create, update and delete specific resources.
    • developer: An internal administrative user of your Keygen account, with permission to manage all resources, but they cannot manage account billing.
    • admin: An internal administrative user of your Keygen account, with permission to manage the entire account.

  • linkmetadata

    hash<string, scalar>

    Hash containing user metadata.

  • linkcreated

    timestamp (ISO8601 format)read only

    When the user was created.

  • linkupdated

    timestamp (ISO8601 format)read only

    When the user was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the user belongs to.

  • linkproducts

    collection

    The products that the user is associated with.

  • linklicenses

    collection

    The licenses that the user owns.

  • linkmachines

    collection

    The machines that the user owns.

  • linktokens

    collection

    The authentication tokens of the user.

Example object

{
  "data": {
    "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
    "type": "users",
    "attributes": {
      "fullName": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "role": "user",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
        }
      }
    }
  }
}

linkCreate a user

Creates a new user resource.

Please note that user resources are shared between products—meaning, when your account has multiple products, your users are signing up for a user profile for all of your products, not just a single product. Your registration verbiage should reflect that. They will be able to login across all of your products with a single user profile, but are licensed per-product.

For example, a user signs up for a "Blizzard" account, not for a "World of Warcraft" account. And with their "Blizzard" account, they will be able to login and buy licenses for "World of Warcraft", "Overwatch", "Starcraft", and for other products which "Blizzard" provides.

linkAuthentication

  • linkNone

    When the account is unprotected, no authentication is required and anybody may create new a user.

  • linkBearer

    required

    When the account is protected, an authentication token with admin privileges or a product token is required.

linkParameters

  • linkaccount

    string, required

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

linkAttributes

  • linkfirstName

    string, optional

    The first name of the user.

  • linklastName

    string, optional

    The last name of the user.

  • linkemail

    string, required

    The unique email of the user.

  • linkpassword

    string, required

    The password for the user.

  • linkrole

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

    The role of the user.

  • linkmetadata

    hash<string, scalar>, optional

    Hash containing user metadata.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  },
  body: JSON.stringify({
    "data": {
      "type": "users",
      "attributes": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "password": "secret"
      }
    }
  })
})

const { data, errors } = await response.json()
import requests
import json

res = requests.post(
  "https://api.keygen.sh/v1/accounts/<%= account %>/users",
  headers={
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  },
  data=json.dumps({
    "data": {
      "type": "users",
      "attributes": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "password": "secret"
      }
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  ],
  parameters: [
    "data": [
      "type": "users",
      "attributes": [
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "password": "secret"
      ]
    ]
  ],
  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("users", Method.POST);

request.AddHeader("Content-Type", "application/vnd.api+json");
request.AddHeader("Accept", "application/vnd.api+json");

request.AddJsonBody(new {
  data = new {
    type = "users",
    attributes = new {
      firstName = "John",
      lastName = "Doe",
      email = "[email protected]",
      password = "secret"
    }
  }
});

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 "users",
    "attributes" to mapOf(
      "firstName" to "John",
      "lastName" to "Doe",
      "email" to "[email protected]",
      "password" to "secret"
    )
  )
))

val res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/users")
  .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", "users"),
    entry("attributes", ofEntries(
      entry("firstName", "John"),
      entry("lastName", "Doe"),
      entry("email", "[email protected]"),
      entry("password", "secret")
    ))
  ))
));

HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/users")
  .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["firstName"] = value::string("John");
attrs["lastName"] = value::string("Doe");
attrs["email"] = value::string("[email protected]");
attrs["password"] = value::string("secret");

value data;
data["type"] = value::string("users");
data["attributes"] = attrs;

value body;
body["data"] = data;

req.headers().add("Content-Type", "application/vnd.api+json");
req.headers().add("Accept", "application/json");

req.set_request_uri("/users");
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 %>/users \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -d '{
        "data": {
          "type": "users",
          "attributes": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "[email protected]",
            "password": "secret"
          }
        }
      }'

Example response / 201 Created

{
  "data": {
    "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
    "type": "users",
    "attributes": {
      "fullName": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "role": "user",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
        }
      }
    }
  }
}

linkRetrieve a user

Retrieves the details of an existing user.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin, the user, or a product.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) or email of the user to be retrieved.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298", {
  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 %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  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(
  "users/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  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 %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298")
  .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 %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298")
  .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("/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298");
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 %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298 \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
    "type": "users",
    "attributes": {
      "fullName": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "role": "user",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
        }
      }
    }
  }
}

linkUpdate a user

Updates the specified user 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, the user, or a product.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the user to be updated.

linkAttributes

  • linkfirstName

    string, optional

    The first name of the user.

  • linklastName

    string, optional

    The last name of the user.

  • linkemail

    string, optional

    The unique email of the user.

  • linkpassword

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

    The password of the user.

  • linkrole

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

    The role of the user.

  • linkmetadata

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

    Hash containing user metadata.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "users",
      "attributes": {
        "metadata": {
          "nickname": "Jack"
        }
      }
    }
  })
})

const { data, errors } = await response.json()
import requests
import json

res = requests.patch(
  "https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  headers={
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  data=json.dumps({
    "data": {
      "type": "users",
      "attributes": {
        "metadata": {
          "nickname": "Jack"
        }
      }
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  method: .patch,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "users",
      "attributes": [
        "metadata": [
          "nickname": "Jack"
        ]
      ]
    ]
  ],
  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(
  "users/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  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 = "users",
    attributes = new {
      metadata = new {
        nickname = "Jack"
      }
    }
  }
});

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 "users",
    "attributes" to mapOf(
      "metadata" to mapOf(
        "nickname" to "Jack"
      )
    )
  )
))

val res = Unirest.patch("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298")
  .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", "users"),
    entry("attributes", ofEntries(
      entry("metadata", ofEntries(
        entry("nickname", "Jack")
      ))
    ))
  ))
));

HttpResponse<JsonNode> res = Unirest.patch("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298")
  .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 metadata;
metadata["nickname"] = value::string("Jack");

value attrs;
attrs["metadata"] = metadata;

value data;
data["type"] = value::string("users");
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("/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298");
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 %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298 \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "users",
          "attributes": {
            "metadata": {
              "nickname": "Jack"
            }
          }
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
    "type": "users",
    "attributes": {
      "fullName": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "role": "user",
      "metadata": {
        "nickname": "Jack"
      },
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
        }
      }
    }
  }
}

linkDelete a user

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

linkAuthentication

  • linkBearer

    required

    An authentication token with admin privileges.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the user to be deleted.

linkReturns

A 204 No Content response will be returned.

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298", {
  method: "DELETE",
  headers: {
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import requests

res = requests.delete(
  "https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
)
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  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(
  "users/a5a154d2-f026-40fa-bc8d-a7e3ca415298",
  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 %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298")
  .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 %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298")
  .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("/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298");
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 %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298 \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkList all users

Returns a list of users. The users are returned sorted by creation date, with the most recent users appearing first. Resources are automatically scoped to the authenticated bearer e.g. when authenticated as a product, only users 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.

linkParameters

  • linkaccount

    string, required

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

linkFilters

  • linklimit

    integer, default is10

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

    https://api.keygen.sh/v1/accounts/<%= account %>/users?limit=25

  • linkpage

    hash<string, integer>

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

    https://api.keygen.sh/v1/accounts/<%= account %>/users?page[size]=15&page[number]=2

  • linkactive

    boolean

    The status of the user to filter by. A user is considered active if they have a license associated with their user.

    https://api.keygen.sh/v1/accounts/<%= account %>/users?active=true

  • linkproduct

    string

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

    https://api.keygen.sh/v1/accounts/<%= account %>/users?product=c6772cd4-c89c-45fa-ab19-395087d79a2d

  • linkroles

    array, default isuser

    Array containing role names to filter by. By default, all non-admin users will be listed i.e. only users with the user role will be displayed. The available user roles can be reviewed here.

    https://api.keygen.sh/v1/accounts/<%= account %>/users?roles[]=admin&roles[]=user

  • linkmetadata

    object

    The metadata object to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/users?metadata[customerId]=cust_af9d94bf5ad4

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users?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 %>/users?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 %>/users?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("users", 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 %>/users")
  .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 %>/users")
  .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("/users");
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 %>/users?limit=15 -g \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": [
    {
      "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
      "type": "users",
      "attributes": {
        "fullName": "John Doe",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "role": "user",
        "metadata": {},
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        },
        "products": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
          }
        },
        "licenses": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
          }
        },
        "machines": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
          }
        },
        "tokens": {
          "links": {
            "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
          }
        }
      }
    },
    …
  ]
}

linkUser actions

Actions for the user resource.

linkUpdate password

Action to update the user's password. A user's password can only be updated when authenticated as the given user.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: the user.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) or email of the user to be retrieved.

linkMeta

  • linkoldPassword

    string, required

    The current password for the user.

  • linknewPassword

    string, required

    The new password for the user.

linkReturns

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

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/users/{ID}/actions/update-password

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/update-password", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer {USER_API_TOKEN}"
  },
  body: JSON.stringify({
    "meta": {
      "oldPassword": "password123",
      "newPassword": "Ep66YCGTD*kc=4AFotPf;[email protected]"
    }
  })
})

const { data, errors } = await response.json()
import requests
import json

res = requests.post(
  "https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/update-password",
  headers={
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer {USER_API_TOKEN}"
  },
  data=json.dumps({
    "meta": {
      "oldPassword": "password123",
      "newPassword": "Ep66YCGTD*kc=4AFotPf;[email protected]"
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/update-password",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "meta": [
      "oldPassword": "password123",
      "newPassword": "Ep66YCGTD*kc=4AFotPf;[email protected]"
    ]
  ],
  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(
  "users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/update-password",
  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 {
    oldPassword = "password123",
    newPassword = "Ep66YCGTD*kc=4AFotPf;[email protected]"
  }
});

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(
    "oldPassword" to "password123",
    "newPassword" to "Ep66YCGTD*kc=4AFotPf;[email protected]"
  )
))

val res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/update-password")
  .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("oldPassword", "password123"),
    entry("newPassword", "Ep66YCGTD*kc=4AFotPf;[email protected]")
  ))
));

HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/update-password")
  .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["oldPassword"] = value::string("password123");
meta["newPassword"] = value::string("Ep66YCGTD*kc=4AFotPf;[email protected]");

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("/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/update-password");
req.set_method(methods::POST);
req.set_body(body.serialize());

client.request(req)
  .then([](http_response res) {
    auto status = res.status_code();
  })
  .wait();
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/update-password \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "meta": {
          "oldPassword": "password123",
          "newPassword": "Ep66YCGTD*kc=4AFotPf;[email protected]"
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
    "type": "users",
    "attributes": {
      "fullName": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "role": "user",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
        }
      }
    }
  }
}

linkReset password

Fulfill a user's password reset request. Password reset tokens expire 24 hours after requesting the reset.

linkAuthentication

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) or email of the user to be retrieved.

linkMeta

  • linkpasswordResetToken

    string, required

    The password reset token emailed to the user.

  • linknewPassword

    string, required

    The new password for the user.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/reset-password", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  },
  body: JSON.stringify({
    "meta": {
      "passwordResetToken": "a9f93c31b41642248db99fc04f4e8482.a5a154d2f02640fabc8da7e3ca415298.96d846eb5cfa38e7282b8eb406926c23cb38edf73c9e15847ac8760427003f5612c6efb5a9005f162462079af2303b79b84d0e78b1aba4c72a7cef7c984d5fv1",
      "newPassword": "Ep66YCGTD*kc=4AFotPf;[email protected]"
    }
  })
})

const { data, errors } = await response.json()
import requests
import json

res = requests.post(
  "https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/reset-password",
  headers={
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  },
  data=json.dumps({
    "meta": {
      "passwordResetToken": "a9f93c31b41642248db99fc04f4e8482.a5a154d2f02640fabc8da7e3ca415298.96d846eb5cfa38e7282b8eb406926c23cb38edf73c9e15847ac8760427003f5612c6efb5a9005f162462079af2303b79b84d0e78b1aba4c72a7cef7c984d5fv1",
      "newPassword": "Ep66YCGTD*kc=4AFotPf;[email protected]"
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/reset-password",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json"
  ],
  parameters: [
    "meta": [
      "passwordResetToken": "a9f93c31b41642248db99fc04f4e8482.a5a154d2f02640fabc8da7e3ca415298.96d846eb5cfa38e7282b8eb406926c23cb38edf73c9e15847ac8760427003f5612c6efb5a9005f162462079af2303b79b84d0e78b1aba4c72a7cef7c984d5fv1",
      "newPassword": "Ep66YCGTD*kc=4AFotPf;[email protected]"
    ]
  ],
  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(
  "users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/reset-password",
  Method.POST
);

request.AddHeader("Content-Type", "application/vnd.api+json");
request.AddHeader("Accept", "application/vnd.api+json");

request.AddJsonBody(new {
  meta = new {
    passwordResetToken = "a9f93c31b41642248db99fc04f4e8482.a5a154d2f02640fabc8da7e3ca415298.96d846eb5cfa38e7282b8eb406926c23cb38edf73c9e15847ac8760427003f5612c6efb5a9005f162462079af2303b79b84d0e78b1aba4c72a7cef7c984d5fv1",
    newPassword = "Ep66YCGTD*kc=4AFotPf;[email protected]"
  }
});

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(
    "passwordResetToken" to "a9f93c31b41642248db99fc04f4e8482.a5a154d2f02640fabc8da7e3ca415298.96d846eb5cfa38e7282b8eb406926c23cb38edf73c9e15847ac8760427003f5612c6efb5a9005f162462079af2303b79b84d0e78b1aba4c72a7cef7c984d5fv1",
    "newPassword" to "Ep66YCGTD*kc=4AFotPf;[email protected]"
  )
))

val res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/reset-password")
  .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("passwordResetToken", "a9f93c31b41642248db99fc04f4e8482.a5a154d2f02640fabc8da7e3ca415298.96d846eb5cfa38e7282b8eb406926c23cb38edf73c9e15847ac8760427003f5612c6efb5a9005f162462079af2303b79b84d0e78b1aba4c72a7cef7c984d5fv1"),
    entry("newPassword", "Ep66YCGTD*kc=4AFotPf;[email protected]")
  ))
));

HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/reset-password")
  .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["passwordResetToken"] = value::string("a9f93c31b41642248db99fc04f4e8482.a5a154d2f02640fabc8da7e3ca415298.96d846eb5cfa38e7282b8eb406926c23cb38edf73c9e15847ac8760427003f5612c6efb5a9005f162462079af2303b79b84d0e78b1aba4c72a7cef7c984d5fv1");
meta["newPassword"] = value::string("Ep66YCGTD*kc=4AFotPf;[email protected]");

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("/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/reset-password");
req.set_method(methods::POST);
req.set_body(body.serialize());

client.request(req)
  .then([](http_response res) {
    auto status = res.status_code();
  })
  .wait();
curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/actions/reset-password \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -d '{
        "meta": {
          "passwordResetToken": "a9f93c31b41642248db99fc04f4e8482.a5a154d2f02640fabc8da7e3ca415298.96d846eb5cfa38e7282b8eb406926c23cb38edf73c9e15847ac8760427003f5612c6efb5a9005f162462079af2303b79b84d0e78b1aba4c72a7cef7c984d5fv1",
          "newPassword": "Ep66YCGTD*kc=4AFotPf;[email protected]"
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "a5a154d2-f026-40fa-bc8d-a7e3ca415298",
    "type": "users",
    "attributes": {
      "fullName": "John Doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "role": "user",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "products": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/products"
        }
      },
      "licenses": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/licenses"
        }
      },
      "machines": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/machines"
        }
      },
      "tokens": {
        "links": {
          "related": "/v1/accounts/<%= account %>/users/a5a154d2-f026-40fa-bc8d-a7e3ca415298/tokens"
        }
      }
    }
  }
}

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

  • linkname

    string

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

  • linkkey

    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.

  • linkexpiry

    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.

  • linkuses

    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.

  • linkprotected

    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.

  • linksuspended

    boolean

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

  • linkfloating

    booleanread only

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

  • linkconcurrent

    booleanread only

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

  • linkscheme

    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.

  • linkstrict

    booleanread only

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

  • linkmaxMachines

    integerread only

    The maximum number of machines the license can have associated with it. This is inherited from the policy.

  • linkmaxCores

    integerread only

    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 inherited from the policy.

  • linkmaxUses

    integerread only

    The maximum number of uses the license is allowed to have. This is inherited from the policy.

  • linkrequireCheckIn

    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.

  • linklastValidated

    timestamp (ISO8601 format)read only

    When the license was last validated.

  • linklastCheckIn

    timestamp (ISO8601 format)read only

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

  • linknextCheckIn

    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.

  • linkmetadata

    hash<string, scalar>

    Hash containing license metadata.

  • linkcreated

    timestamp (ISO8601 format)read only

    When the license was created.

  • linkupdated

    timestamp (ISO8601 format)read only

    When the license was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the license belongs to.

  • linkproduct

    individual

    The product that the license is associated with.

  • linkpolicy

    individual

    The policy that the license implements.

  • linkuser

    individual

    The user that owns the license.

  • linkmachines

    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": "<%= expiry %>",
      "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": "<%= now %>",
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

linkAttributes

  • linkname

    string, optional

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

  • linkkey

    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.

  • linkexpiry

    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.

  • linkprotected

    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.

  • linksuspended

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

    Whether or not the license is suspended.

  • linkmetadata

    hash<string, scalar>, optional

    Hash containing license metadata.

linkRelationships

  • linkpolicy

    linkage, required

    The policy to implement for the license.

  • linkuser

    linkage, 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.

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": "<%= expiry %>",
      "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": "<%= created %>",
      "updated": "<%= created %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    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.

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": "<%= expiry %>",
      "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": "<%= now %>",
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

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

linkAttributes

  • linkname

    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.

  • linkexpiry

    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.

  • linkprotected

    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.

  • linksuspended

    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.

  • linkmetadata

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

    Hash containing license metadata.

linkReturns

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

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",
      "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": "<%= now %>",
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

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

linkReturns

A 204 No Content response will be returned.

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.

linkParameters

  • linkaccount

    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

    hash<string, integer>

    Hash 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

  • linksuspended

    boolean

    The suspended status of the license to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/licenses?suspended=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) 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

    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.

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": "<%= expiry %>",
        "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": "<%= now %>",
        "lastCheckIn": null,
        "nextCheckIn": null,
        "metadata": {},
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    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.

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": "<%= now %>",
    "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",
      "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": "<%= now %>",
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "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 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.
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.
FINGERPRINT_SCOPE_REQUIRED The validated license requires a fingerprint scope to be provided during validation.
FINGERPRINT_SCOPE_MISMATCH 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.
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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

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

linkMeta

  • linknonce

    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.

  • linkscope

    hash<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.

  • linkscope.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.

  • linkscope.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.

  • linkscope.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.

  • linkscope.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.

  • linkscope.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.

  • linkscope.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.

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": "<%= now %>",
    "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": "<%= expired %>",
      "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": "<%= now %>",
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "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 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.
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.
FINGERPRINT_SCOPE_REQUIRED The validated license requires a fingerprint scope to be provided during validation.
FINGERPRINT_SCOPE_MISMATCH 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.
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

linkParameters

  • linkaccount

    string, required

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

linkMeta

  • linkkey

    string, required

    The license key to validate.

  • linknonce

    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.

  • linkscope

    hash<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.

  • linkscope.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.

  • linkscope.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.

  • linkscope.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.

  • linkscope.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.

  • linkscope.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.

  • linkscope.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.

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": "<%= now %>",
    "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": "<%= expired %>",
      "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": "<%= now %>",
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    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.

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",
      "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": "<%= now %>",
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    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.

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",
      "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": "<%= now %>",
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    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.

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",
      "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": "<%= now %>",
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    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.

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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    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.

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",
      "uses": 0,
      "protected": false,
      "suspended": false,
      "encrypted": false,
      "floating": true,
      "concurrent": true,
      "strict": false,
      "maxMachines": 5,
      "maxCores": 64,
      "maxUses": null,
      "requireCheckIn": true,
      "lastValidated": "<%= now %>",
      "lastCheckIn": "<%= lastCheckIn %>",
      "nextCheckIn": "<%= nextCheckIn %>",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

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

linkMeta

  • linkincrement

    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.

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",
      "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": "<%= now %>",
      "lastCheckIn": "<%= lastCheckIn %>",
      "nextCheckIn": "<%= nextCheckIn %>",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

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

linkMeta

  • linkdecrement

    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.

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",
      "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": "<%= now %>",
      "lastCheckIn": "<%= lastCheckIn %>",
      "nextCheckIn": "<%= nextCheckIn %>",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    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.

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",
      "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": "<%= now %>",
      "lastCheckIn": "<%= lastCheckIn %>",
      "nextCheckIn": "<%= nextCheckIn %>",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "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"
        }
      }
    }
  }
}

linkLicense relationships

Relationship endpoints for the license resource.

linkGenerate an activation token

Create an activation token for a license. An activation token has permission to activate and deactivate machines for the given license.

A typical machine activation flow using activation tokens will require you to deliver the license key, as well as the activation token to your customer (e.g. via email). In this scenario, you would generate an activation token after creating a license for them, all of which would likely be done after purchase.

Alternatively, you could also store the activation token in the license's metadata attribute. Bearing in mind any expiry value, doing this allows you to deliver the license key to the customer, and the activation token will be included in all license validation responses for further requests, e.g. machine activation.

Providing the customer with both the activation token and the license key will allow them to validate their license and activate/deactivate machines without having to sign up for a user profile, since the machine-related endpoints require API authentication.

For an example of utilizing activation tokens, check out our machine activation example on GitHub.

linkAuthentication

  • linkBearer

    required

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

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) or key of the license the token is for. Cannot be a legacy encrypted license key.

linkAttributes

  • linkexpiry

    timestamp (ISO8601 format), optional

    The timestamp for when the token expires. Requests using an expired token will be rejected.

  • linkmaxActivations

    integer, optional

    The maximum number of machine activations the token is allowed to perform. If this is null, the token will not have an activation limit.

  • linkmaxDeactivations

    integer, optional

    The maximum number of machine deactivations the token is allowed to perform. If this is null, the token will not have a deactivation limit.

linkReturns

A 200 OK response will be returned along with the new activation token.

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "tokens",
      "attributes": {
        "maxActivations": 2
      }
    }
  })
})

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/tokens",
  headers={
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  data=json.dumps({
    "data": {
      "type": "tokens",
      "attributes": {
        "maxActivations": 2
      }
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "tokens",
      "attributes": [
        "maxActivations": 2
      ]
    ]
  ],
  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/tokens",
  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 = "tokens",
    attributes = new {
      maxActivations = 2
    }
  }
});

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 "tokens",
    "attributes" to mapOf(
      "maxActivations" to 2
    )
  )
))

val res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens")
  .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", ofEntries(
    entry("type", "tokens"),
    entry("attributes", ofEntries(
      entry("maxActivations", 2)
    ))
  ))
));

HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/tokens")
  .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["maxActivations"] = value::number(2);

value data;
data["type"] = value::string("tokens");
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/tokens");
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/tokens \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "tokens",
          "attributes": {
            "maxActivations": 2
          }
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "8ae9291c-46f7-48f9-b115-eb406ef01b1b",
    "type": "tokens",
    "attributes": {
      "kind": "activation-token",
      "token": "activ-70c5a0266f9f47423454d6ba1e4faeb1v3",
      "expiry": null,
      "maxActivations": 2,
      "activations": 0,
      "maxDeactivations": null,
      "deactivations": 0,
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
        },
        "data": {
          "type": "licenses",
          "id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827"
        }
      }
    }
  }
}

linkAttach license entitlements

Attach entitlements to a license. This will immediately be taken into effect for all future validations.

Below are the limitations to attaching an entitlement:

  • You cannot attach an entitlement that is already attached through the policy.
  • 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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) or key of the license to be updated. Cannot be a legacy encrypted license key.

linkReturns

A 201 Created response will be returned along with an array of license-entitlement objects.

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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(
  "licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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("/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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": "license-entitlements",
      "attributes": {
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "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"
          }
        },
        "license": {
          "links": {
            "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827"
          },
          "data": {
            "type": "licenses",
            "id": "b18e3f3a-330c-4d8d-ae2e-014db21fa827"
          }
        }
      },
      "links": {
        "related": "/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements/57f1ceb4-6bf4-44dd-8967-de88364bf9eb"
      }
    }
  ]
}

linkDetach license entitlements

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

Below are the limitations to detaching an entitlement:

  • You cannot detach an entitlement that is attached through the policy.

linkAuthentication

  • linkBearer

    required

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

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) or key of the license to be updated. Cannot be a legacy encrypted license key.

linkReturns

A 204 No Content response will be returned.

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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(
  "licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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("/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 license entitlements

Returns a list of entitlements attached to the license. The entitlements are returned sorted by creation date, with the most recent entitlements appearing first. The listed entitlements include all entitlements attached to the license's policy, in additon to the entitlements attached to the particular 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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements?limit=25

  • linkpage

    hash<string, integer>

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

    https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/entitlements?page[size]=15&page[number]=2

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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("/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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 %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/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": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        }
      },
      "links": {
        "self": "/v1/accounts/<%= account %>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded"
      }
    },
    …
  ]
}

linkChange policy

Change a license's policy relationship. This will immediately be taken into effect for all future validations.

Below are the limitations to changing a license's policy:

  • You cannot change from an encrypted policy to an unencrypted policy (or vice-versa).
  • You cannot change from a pooled policy to an unpooled policy (or vice-versa).
  • You cannot change to a policy that has a different cryptographic scheme.
  • You cannot change to a policy that has a different fingerprint strategy.
  • You cannot change to a policy for another product.

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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) or key of the license to be updated. Cannot be a legacy encrypted license key.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy", {
  method: "PUT",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "policies",
      "id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
    }
  })
})

const { data, errors } = await response.json()
import requests
import json

res = requests.put(
  "https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy",
  headers={
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  data=json.dumps({
    "data": {
      "type": "policies",
      "id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy",
  method: .put,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "policies",
      "id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
    ]
  ],
  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/policy",
  Method.PUT
);

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",
    id = "70af414d-6152-4ff1-892b-15a40ada6b4e"
  }
});

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",
    "id" to "70af414d-6152-4ff1-892b-15a40ada6b4e"
  )
))

val res = Unirest.put("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy")
  .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("id", "70af414d-6152-4ff1-892b-15a40ada6b4e")
  ))
));

HttpResponse<JsonNode> res = Unirest.put("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy")
  .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 data;
data["type"] = value::string("policies");
data["id"] = value::string("70af414d-6152-4ff1-892b-15a40ada6b4e");

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/policy");
req.set_method(methods::PUT);
req.set_body(body.serialize());

client.request(req)
  .then([](http_response res)
  {
    auto data = res.extract_json().get();
  })
  .wait();
curl -X PUT https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/policy \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "policies",
          "id": "70af414d-6152-4ff1-892b-15a40ada6b4e"
        }
      }'

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",
      "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": "<%= now %>",
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "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"
        }
      }
    }
  }
}

linkChange user

Change a license's user relationship. This will immediately transfer the license resource to the new user.

linkAuthentication

  • linkBearer

    required

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

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) or key of the license to be updated. Cannot be a legacy encrypted license key.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user", {
  method: "PUT",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "users",
      "id": "192bd216-58cc-47a8-bd2d-667e0b729c43"
    }
  })
})

const { data, errors } = await response.json()
import requests
import json

res = requests.put(
  "https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user",
  headers={
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  data=json.dumps({
    "data": {
      "type": "users",
      "id": "192bd216-58cc-47a8-bd2d-667e0b729c43"
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user",
  method: .put,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "users",
      "id": "192bd216-58cc-47a8-bd2d-667e0b729c43"
    ]
  ],
  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/user",
  Method.PUT
);

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 = "users",
    id = "192bd216-58cc-47a8-bd2d-667e0b729c43"
  }
});

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 "users",
    "id" to "192bd216-58cc-47a8-bd2d-667e0b729c43"
  )
))

val res = Unirest.put("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user")
  .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", "users"),
    entry("id", "192bd216-58cc-47a8-bd2d-667e0b729c43")
  ))
));

HttpResponse<JsonNode> res = Unirest.put("https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user")
  .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 data;
data["type"] = value::string("users");
data["id"] = value::string("192bd216-58cc-47a8-bd2d-667e0b729c43");

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/user");
req.set_method(methods::PUT);
req.set_body(body.serialize());

client.request(req)
  .then([](http_response res)
  {
    auto data = res.extract_json().get();
  })
  .wait();
curl -X PUT https://api.keygen.sh/v1/accounts/<%= account %>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/user \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "users",
          "id": "192bd216-58cc-47a8-bd2d-667e0b729c43"
        }
      }'

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",
      "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": "<%= now %>",
      "lastCheckIn": null,
      "nextCheckIn": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "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": "192bd216-58cc-47a8-bd2d-667e0b729c43"
        }
      },
      "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"
        }
      }
    }
  }
}

linkMachines

linkThe machine object

Below you will find the various attributes for the machine resource, as well as the machine resource's relationships. Machines can be used to track and manage where your users are allowed to use your product.

linkAttributes

  • linkfingerprint

    string

    The fingerprint of the machine. This can be an arbitrary string, but must be unique within the scope of the license it belongs to.

  • linkcores

    integer

    The number of CPU cores for the machine.

  • linkname

    string

    The human-readable name of the machine.

  • linkip

    string

    The IP of the machine.

  • linkhostname

    string

    The hostname of the machine.

  • linkplatform

    string

    The platform of the machine.

  • linkrequireHeartbeat

    booleanread only

    Whether or not the machine has an active heartbeat monitor and requires pings.

  • linkheartbeatStatus

    stringread only

    The status of the machine's heartbeat. One of: NOT_STARTED, ALIVE or DEAD.

  • linkheartbeatDuration

    integerread only

    The policy's heartbeat duration. When a heartbeat monitor is active, the machine must send a heartbeat ping within this timeframe to remain activated.

  • linklastHeartbeat

    timestamp (ISO8601 format)read only

    When the machine last sent a heartbeat ping. This is null if the machine does not require a heartbeat.

  • linknextHeartbeat

    timestamp (ISO8601 format)read only

    The time at which the machine is required to send a heartbeat ping by. This is null if the machine does not require a heartbeat.

  • linkmetadata

    hash<string, scalar>

    Hash containing machine metadata.

  • linkcreated

    timestamp (ISO8601 format)read only

    When the machine was created.

  • linkupdated

    timestamp (ISO8601 format)read only

    When the machine was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the machine belongs to.

  • linkproduct

    individual

    The product that the machine is associated with.

  • linklicense

    individual

    The license that the machine is associated with.

  • linkuser

    individual

    The user that owns the machine.

Example object

{
  "data": {
    "id": "9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
    "type": "machines",
    "links": {
      "self": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4"
    },
    "attributes": {
      "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
      "cores": null,
      "ip": null,
      "hostname": null,
      "platform": "macOS",
      "name": "Office MacBook Pro",
      "requireHeartbeat": false,
      "heartbeatStatus": "NOT_STARTED",
      "heartbeatDuration": 600,
      "lastHeartbeat": null,
      "nextHeartbeat": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/product"
        },
        "data": {
          "type": "products",
          "id": "22b78db6-6a2e-4a7f-9369-157976148c4c"
        }
      },
      "license": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/license"
        },
        "data": {
          "type": "licenses",
          "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/user"
        },
        "data": {
          "type": "users",
          "id": "15ad7012-b570-48b7-88c1-fbab68be9d05"
        }
      }
    }
  }
}

linkActivate a machine

Creates, or activates, a new machine resource for a license. A license can have a maximum of 500 machines associated with it at any one time. If you need a higher limit, please reach out to us.

linkAuthentication

  • linkBearer

    required

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

linkParameters

  • linkaccount

    string, required

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

linkAttributes

  • linkfingerprint

    string, required

    The fingerprint of the machine. This can be an arbitrary string, but must be unique within the scope of the license it belongs to.

  • linkcores

    integer, optional

    The number of CPU cores for the machine.

  • linkname

    string, optional

    The human-readable name of the machine.

  • linkip

    string, optional

    The IP of the machine.

  • linkhostname

    string, optional

    The hostname of the machine.

  • linkplatform

    string, optional

    The platform of the machine.

  • linkmetadata

    hash<string, scalar>, optional

    Hash containing machine metadata.

linkRelationships

  • linklicense

    linkage, required

    The license the machine is for.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/machines", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "machines",
      "attributes": {
        "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
        "platform": "macOS",
        "name": "Office MacBook Pro"
      },
      "relationships": {
        "license": {
          "data": {
            "type": "licenses",
            "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
          }
        }
      }
    }
  })
})

const { data, errors } = await response.json()
import requests
import json

res = requests.post(
  "https://api.keygen.sh/v1/accounts/<%= account %>/machines",
  headers={
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  data=json.dumps({
    "data": {
      "type": "machines",
      "attributes": {
        "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
        "platform": "macOS",
        "name": "Office MacBook Pro"
      },
      "relationships": {
        "license": {
          "data": {
            "type": "licenses",
            "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
          }
        }
      }
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/machines",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "machines",
      "attributes": [
        "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
        "platform": "macOS",
        "name": "Office MacBook Pro"
      ],
      "relationships": [
        "license": [
          "data": [
            "type": "licenses",
            "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
          ]
        ]
      ]
    ]
  ],
  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("machines", 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 = "machines",
    attributes = new {
      fingerprint = "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
      platform = "macOS",
      name = "Office MacBook Pro"
    },
    relationships = new {
      license = new {
        data = new {
          type = "licenses",
          id = "4097d726-6cc5-4156-8575-3a96387e19b4"
        }
      }
    }
  }
});

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 "machines",
    "attributes" to mapOf(
      "fingerprint" to "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
      "platform" to "macOS",
      "name" to "Office MacBook Pro"
    ),
    "relationships" to mapOf(
      "license" to mapOf(
        "data" to mapOf(
          "type" to "licenses",
          "id" to "4097d726-6cc5-4156-8575-3a96387e19b4"
        )
      )
    )
  )
))

val res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/machines")
  .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", "machines"),
    entry("attributes", ofEntries(
      entry("fingerprint", "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC"),
      entry("platform", "macOS"),
      entry("name", "Office MacBook Pro")
    )),
    entry("relationships", ofEntries(
      entry("license", ofEntries(
        entry("data", ofEntries(
          entry("type", "licenses"),
          entry("id", "4097d726-6cc5-4156-8575-3a96387e19b4")
        ))
      ))
    ))
  ))
));

HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/machines")
  .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["fingerprint"] = value::string("4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC");
attrs["platform"] = value::string("macOS");
attrs["name"] = value::string("Office MacBook Pro");

value license_;
license_["type"] = value::string("licenses");
license_["id"] = value::string("4097d726-6cc5-4156-8575-3a96387e19b4");

value license;
license["data"] = license_;

value rels;
rels["license"] = license;

value data;
data["type"] = value::string("machines");
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("/machines");
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 %>/machines \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "machines",
          "attributes": {
            "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
            "platform": "macOS",
            "name": "Office MacBook Pro"
          },
          "relationships": {
            "license": {
              "data": {
                "type": "licenses",
                "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
              }
            }
          }
        }
      }'

Example response / 201 Created

{
  "data": {
    "id": "9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
    "type": "machines",
    "links": {
      "self": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4"
    },
    "attributes": {
      "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
      "cores": null,
      "ip": null,
      "hostname": null,
      "platform": "macOS",
      "name": "Office MacBook Pro",
      "requireHeartbeat": false,
      "heartbeatStatus": "NOT_STARTED",
      "heartbeatDuration": 600,
      "lastHeartbeat": null,
      "nextHeartbeat": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/product"
        },
        "data": {
          "type": "products",
          "id": "22b78db6-6a2e-4a7f-9369-157976148c4c"
        }
      },
      "license": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/license"
        },
        "data": {
          "type": "licenses",
          "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/user"
        },
        "data": {
          "type": "users",
          "id": "15ad7012-b570-48b7-88c1-fbab68be9d05"
        }
      }
    }
  }
}

linkRetrieve a machine

Retrieves the details of an existing machine.

linkAuthentication

  • linkBearer

    required

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

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) or URL-safe fingerprint of the machine to be retrieved.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/machines/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 %>/machines/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 %>/machines/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(
  "machines/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 %>/machines/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 %>/machines/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("/machines/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 %>/machines/eef41cf5-f32e-4dab-a867-b9738d87285b \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
    "type": "machines",
    "links": {
      "self": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4"
    },
    "attributes": {
      "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
      "cores": null,
      "ip": null,
      "hostname": null,
      "platform": "macOS",
      "name": "Office MacBook Pro",
      "requireHeartbeat": false,
      "heartbeatStatus": "NOT_STARTED",
      "heartbeatDuration": 600,
      "lastHeartbeat": null,
      "nextHeartbeat": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/product"
        },
        "data": {
          "type": "products",
          "id": "22b78db6-6a2e-4a7f-9369-157976148c4c"
        }
      },
      "license": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/license"
        },
        "data": {
          "type": "licenses",
          "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/user"
        },
        "data": {
          "type": "users",
          "id": "15ad7012-b570-48b7-88c1-fbab68be9d05"
        }
      }
    }
  }
}

linkUpdate a machine

Updates the specified machine 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, the product it belongs to, or the user it belongs to (unless the license is protected).

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) or URL-safe fingerprint of the machine to be updated.

linkAttributes

  • linkcores

    integer, optional

    The number of CPU cores for the machine.

  • linkname

    string, optional

    The human-readable name of the machine.

  • linkip

    string, optional

    The IP of the machine.

  • linkhostname

    string, optional

    The hostname of the machine.

  • linkplatform

    string, optional

    The platform of the machine.

  • linkmetadata

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

    Hash containing machine metadata.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/machines/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": "machines",
      "attributes": {
        "ip": "192.168.1.1"
      }
    }
  })
})

const { data, errors } = await response.json()
import requests
import json

res = requests.patch(
  "https://api.keygen.sh/v1/accounts/<%= account %>/machines/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": "machines",
      "attributes": {
        "ip": "192.168.1.1"
      }
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/machines/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": "machines",
      "attributes": [
        "ip": "192.168.1.1"
      ]
    ]
  ],
  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(
  "machines/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 = "machines",
    attributes = new {
      ip = "192.168.1.1"
    }
  }
});

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 "machines",
    "attributes" to mapOf(
      "ip" to "192.168.1.1"
    )
  )
))

val res = Unirest.patch("https://api.keygen.sh/v1/accounts/<%= account %>/machines/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", "machines"),
    entry("attributes", ofEntries(
      entry("ip", "192.168.1.1")
    ))
  ))
));

HttpResponse<JsonNode> res = Unirest.patch("https://api.keygen.sh/v1/accounts/<%= account %>/machines/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["ip"] = value::string("192.168.1.1");

value data;
data["type"] = value::string("machines");
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("/machines/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 %>/machines/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": "machines",
          "attributes": {
            "ip": "192.168.1.1",
            "cores": 16
          }
        }
      }'

Example response / 200 OK

{
  "data": {
    "id": "9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
    "type": "machines",
    "links": {
      "self": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4"
    },
    "attributes": {
      "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
      "cores": 16,
      "ip": "192.168.1.1",
      "hostname": null,
      "platform": "macOS",
      "name": "Office MacBook Pro",
      "requireHeartbeat": false,
      "heartbeatStatus": "NOT_STARTED",
      "heartbeatDuration": 600,
      "lastHeartbeat": null,
      "nextHeartbeat": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= updated %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/product"
        },
        "data": {
          "type": "products",
          "id": "22b78db6-6a2e-4a7f-9369-157976148c4c"
        }
      },
      "license": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/license"
        },
        "data": {
          "type": "licenses",
          "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/user"
        },
        "data": {
          "type": "users",
          "id": "15ad7012-b570-48b7-88c1-fbab68be9d05"
        }
      }
    }
  }
}

linkDeactivate a machine

Permanently deletes, or deactivates, a machine. It cannot be undone.

linkAuthentication

  • linkBearer

    required

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

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) or URL-safe fingerprint of the machine to be deleted.

linkReturns

A 204 No Content response will be returned.

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4", {
  method: "DELETE",
  headers: {
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
})
import requests

res = requests.delete(
  "https://api.keygen.sh/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
)
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
  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(
  "machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
  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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4")
  .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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4")
  .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("/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4");
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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4 \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 204 No Content

No content

linkList all machines

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

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to view the resources: either an admin, a product which the owning license belongs to, the license which the machines belong to (via an activation token), or the user which the machines belong to.

linkParameters

  • linkaccount

    string, required

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

linkFilters

  • linklimit

    integer, default is10

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

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?limit=25

  • linkpage

    hash<string, integer>

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

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?page[size]=15&page[number]=2

  • linkfingerprint

    string

    The machine fingerprint to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?fingerprint=4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC

  • linkip

    string

    The machine IP address to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?ip=192.168.1.1

  • linkhostname

    string

    The machine hostname to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?hostname=CoolHostname

  • linkproduct

    string

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

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?product=3ab38aae-bbf7-4846-9c32-af9d94bf5ad4

  • linkpolicy

    string

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

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?policy=f2a336e8-85c0-49bd-85f6-ffc15b4ac679

  • linklicense

    string

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

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?license=3fd7ff1c-e778-4030-a81c-d2242d909258

  • linkkey

    string

    The license key to filter by. Cannot be an encrypted key.

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?key=C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3

  • linkuser

    string

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

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?user=a5a154d2-f026-40fa-bc8d-a7e3ca415298

  • linkmetadata

    object

    The metadata object to filter by.

    https://api.keygen.sh/v1/accounts/<%= account %>/machines?metadata[nodeId]=68666bf8b

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/machines?limit=15", {
  method: "GET",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "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 %>/machines?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 %>/machines?limit=15",
  headers: [
    "Content-Type": "application/vnd.api+json",
    "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("machines", 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 %>/machines")
  .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 %>/machines")
  .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("/machines");
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 %>/machines?limit=15 -g \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": [
    {
      "id": "9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
      "type": "machines",
      "links": {
        "self": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4"
      },
      "attributes": {
        "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
        "cores": null,
        "ip": null,
        "hostname": null,
        "platform": "macOS",
        "name": "Office MacBook Pro",
        "requireHeartbeat": false,
        "heartbeatStatus": "NOT_STARTED",
        "heartbeatDuration": 600,
        "lastHeartbeat": null,
        "nextHeartbeat": null,
        "metadata": {},
        "created": "<%= created %>",
        "updated": "<%= created %>"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<%= account %>"
          },
          "data": {
            "type": "accounts",
            "id": "<%= account %>"
          }
        },
        "product": {
          "links": {
            "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/product"
          },
          "data": {
            "type": "products",
            "id": "22b78db6-6a2e-4a7f-9369-157976148c4c"
          }
        },
        "license": {
          "links": {
            "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/license"
          },
          "data": {
            "type": "licenses",
            "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
          }
        },
        "user": {
          "links": {
            "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/user"
          },
          "data": {
            "type": "users",
            "id": "15ad7012-b570-48b7-88c1-fbab68be9d05"
          }
        }
      }
    },
    …
  ]
}

linkMachine actions

Actions for the machine resource.

linkOffline activation proofs

Action to generate a cryptographically signed offline activation proof. This can be used to implement an offline license activation system. You can think of these proofs as a 'certificate' or a 'license file.' See our sample client/server app on GitHub for an example of air-gapped license activation.

Activation proofs are signed with your account's 2048-bit RSA private key, using RSA PKCS1 v1.5 padding, with a SHA256 digest. The proof dataset will be base64url encoded and then prefixed with proof/ 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. proof/{URLBASE64_DATASET}.{URLBASE64_SIGNATURE}.

Here is an example of a cryptographically signed activation proof:

proof/eyJhY2NvdW50Ijp7ImlkIjoiMmUyOTE2N2ItZjc1NS00YjlkLTk1OWMtZTIzNmI1OTY5N2IzIn0sInByb2R1Y3QiOnsiaWQiOiI0MTdkODNjMy1jMjhkLTRhMDMtODQwYS00Y2ZmNmUzNTUyZTYifSwicG9saWN5Ijp7ImlkIjoiMTI2MzczY2QtYTA2Mi00MDYzLTgwODUtZDE3N2MyNTM0MTg3IiwiZHVyYXRpb24iOjEyMDk2MDB9LCJsaWNlbnNlIjp7ImlkIjoiMzg3ZjUxMmQtOTJjYy00Y2UzLWE3MTAtY2FjOGJkZGU3NzU1Iiwia2V5IjoiRUREMEIxLTAwQzhBNi04MzdGQzAtRDlGQTkyLUJGNjFBMS1WMyIsImV4cGlyeSI6IjIwMjEtMDQtMDVUMTc6MDQ6NTUuMjEzWiJ9LCJtYWNoaW5lIjp7ImlkIjoiN2ZhNzA3YzAtY2FhNi00NTI0LThlNTItNmEzNDQyMzUwNzVlIiwiZmluZ2VycHJpbnQiOiI4Qjo5Mjo1RDpERToxRDpFODozNjpEMjo4ODpFNzo2RTo0QSIsImNyZWF0ZWQiOiIyMDIxLTAzLTIyVDE3OjA0OjU1LjIyNFoifSwidHMiOiIyMDIxLTAzLTIyVDE3OjA0OjU2LjgzNFoifQ==.mJfXlfBbG8ekOph8SmDNiuRcL9sz_RSecwF4Q4hz1rd8gJOFN-fwhnt3Pd9rIGpr09_-4UPzqBeC0W_ak905F4iGVi57JK2b1qegjbe22R1XtqfFlvpHPvuez6lkhkRy8YOpe80PpWxyFuXCGwHJ65cSBFL6r6PvOqWG2IdacaolDdR76ek1z4bf5RWI-MEJFlJpQcJ_Cr8PjmssR4A270ZxhKlFGG-0wsut504l_XcmHH_IUmyvPTIAhoWV496pCSQSGGw6r4Y9BElKk1Vlm8tUMQ6JQMlbHjWkwWyd950r-0a1-AUw7kAMHKiR4SQTQGLumQhMe0v9Io6GLJeaQA==

Below is the decoded dataset from the above example proof:

{
  "account": {
    "id": "2e29167b-f755-4b9d-959c-e236b59697b3"
  },
  "product": {
    "id": "417d83c3-c28d-4a03-840a-4cff6e3552e6"
  },
  "policy": {
    "id": "126373cd-a062-4063-8085-d177c2534187",
    "duration": 1209600
  },
  "license": {
    "id": "387f512d-92cc-4ce3-a710-cac8bdde7755",
    "key": "EDD0B1-00C8A6-837FC0-D9FA92-BF61A1-V3",
    "expiry": "2021-04-05T17:04:55.213Z"
  },
  "machine": {
    "id": "7fa707c0-caa6-4524-8e52-6a344235075e",
    "fingerprint": "8B:92:5D:DE:1D:E8:36:D2:88:E7:6E:4A",
    "created": "2021-03-22T17:04:55.224Z"
  },
  "ts": "2021-03-22T17:04:56.834Z"
}

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to generate an offline proof: 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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) or URL-safe fingerprint of the machine to generate an offline activation proof for.

linkMeta

  • linkdataset

    hash<string, scalar>, optional

    A custom JSON dataset to embed within the activation proof. This dataset will be cryptographically signed, making it tamper-proof. Only authenticated admins and products may supply this value.

linkReturns

A 200 OK response will be returned along with an offline activation proof and the machine object.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/machines/{ID}/actions/generate-offline-proof

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/generate-offline-proof", {
  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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/generate-offline-proof",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/generate-offline-proof",
  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(
  "machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/ping-heartbeat",
  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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/generate-offline-proof")
  .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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/generate-offline-proof")
  .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("/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/generate-offline-proof");
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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/generate-offline-proof \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "meta": {
    "proof": "proof/eyJhY2NvdW50Ijp7ImlkIjoiNjI0NzBkNjctNDgzNy00YjVhLWFjYzItN2FmYjgwZDBhM2JmIn0sInByb2R1Y3QiOnsiaWQiOiJhNzZiM2NhMi1hZGVlLTRiY2YtOTdhMS0xNzkyNDAzMWNlY2QifSwicG9saWN5Ijp7ImlkIjoiN2Y4OTlhMTUtNDU1My00YjkwLWI3MzAtNmUxZjgwMzEyYzcwIn0sImxpY2Vuc2UiOnsiaWQiOiIzMWZhMzU1MS1kYjJmLTRmN2UtYjEzMS0yZGZiNTViZmJmNzMiLCJrZXkiOiJERkU1NzktNzUzQzI1LUEzQjY2Ny0yNEUzRUMtMzI4QTU3LVYzIiwiZXhwaXJ5IjoiMjAyMS0wMy0yOVQyMjo0NzowOS4xMDhaIn0sIm1hY2hpbmUiOnsiaWQiOiJkZWMwNmE5YS1kZTVjLTQ1M2MtYTAyMy1jOTMwMjlkZjMzMjMiLCJmaW5nZXJwcmludCI6ImRjMTY0MmI5NjcyMTFlODVmMTRmNjRjZmE4NjdjODZjIiwiY3JlYXRlZCI6IjIwMjAtMTAtMDFUMTc6MTM6MTkuNzI1WiJ9LCJwcm9vZiI6eyJjcmVhdGVkIjoiMjAyMC0xMC0wNVQyMDo0MDozMi4xNDNaIn19.QpyUpB2PMXC4QmQfKvStoafV5F4WIvzaF3IJ8SEd2YVfhicbRxZp4EiJRkKt_la4TaBF7MzWeqaXfbMVDk_LAKAWlTFgeFNBF0B9pXyCWHgFc01AKeiz6l3Cwi-PsC-DP6yfMgQqZ2LKOruIbkuWHL8yrTBw9n5_LSRldR8OAxVY51o0bdWRiYHO1jtkq2MFbn8t3tS8p0bJacuHRrWJSl6WAYZYb3iLXLiuftSrX6cZuB_ZlVifWvXXl3Am_ebOBnZ7WQBsTfJ0xxHFKbIpn24s9LGlIf0kJOEk4zr8vc9mxxyIFh1HwbGKTQzpj9sW6rFiVY5a9zMQLKh3ciDjRQ=="
  },
  "data": {
    "id": "9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
    "type": "machines",
    "links": {
      "self": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4"
    },
    "attributes": {
      "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
      "cores": null,
      "ip": null,
      "hostname": null,
      "platform": "macOS",
      "name": "Office MacBook Pro",
      "requireHeartbeat": true,
      "heartbeatStatus": "ALIVE",
      "heartbeatDuration": 600,
      "lastHeartbeat": "2019-05-28T15:38:02.927Z",
      "nextHeartbeat": "2019-05-28T15:48:02.927Z",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/product"
        },
        "data": {
          "type": "products",
          "id": "22b78db6-6a2e-4a7f-9369-157976148c4c"
        }
      },
      "license": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/license"
        },
        "data": {
          "type": "licenses",
          "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/user"
        },
        "data": {
          "type": "users",
          "id": "15ad7012-b570-48b7-88c1-fbab68be9d05"
        }
      }
    }
  }
}

linkPing heartbeat

Action to begin and maintain a machine heartbeat monitor. When a machine has not performed a heartbeat ping within the monitor window, it will automatically be deactivated. This can be utilized for machine leasing, where a license has a limited number of machines allowed, and each machine must maintain heartbeat pings in order to remain active.

To illustrate further, consider a rather common scenario when dealing with leasing VMs:

  1. The machine is activated for a new device using a unique VM GUID as a "fingerprint."
  2. The machine sends their first heartbeat ping, starting the monitor.
  3. The machine sends further heartbeat pings, within the heartbeat monitor window, to indicate that it is still alive.
  4. The machine/software crashes. Normal machine deactivation fails to occur before the software program exits. This is now a "zombie" machine.
  5. The heartbeat monitor detects that the machine has not sent a ping within the window, and subsequently deactivates the machine.

The default heartbeat monitor window is 10 minutes from time of last ping. This can be configured via the license policy's heartbeatDuration attribute.

Once a machine heartbeat monitor has been started, it must be maintained. The machine will automatically be deactivated (i.e. deleted) if it does not maintain a ping frequency. Please see the reset heartbeat action, which can be used to reset and disable a heartbeat monitor for a given machine.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to ping the resource's heartbeat: either an admin, the product it belongs to, the machine's license (via an activation token), or the user it belongs to.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) or URL-safe fingerprint of the machine to ping.

linkReturns

A 200 OK response will be returned along with the pinged machine object.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/machines/{ID}/actions/ping-heartbeat

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/ping-heartbeat", {
  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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/ping-heartbeat",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/ping-heartbeat",
  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(
  "machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/ping-heartbeat",
  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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/ping-heartbeat")
  .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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/ping-heartbeat")
  .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("/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/ping-heartbeat");
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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/ping-heartbeat \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
    "type": "machines",
    "links": {
      "self": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4"
    },
    "attributes": {
      "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
      "cores": null,
      "ip": null,
      "hostname": null,
      "platform": "macOS",
      "name": "Office MacBook Pro",
      "requireHeartbeat": true,
      "heartbeatStatus": "ALIVE",
      "heartbeatDuration": 600,
      "lastHeartbeat": "2019-05-28T15:38:02.927Z",
      "nextHeartbeat": "2019-05-28T15:48:02.927Z",
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/product"
        },
        "data": {
          "type": "products",
          "id": "22b78db6-6a2e-4a7f-9369-157976148c4c"
        }
      },
      "license": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/license"
        },
        "data": {
          "type": "licenses",
          "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/user"
        },
        "data": {
          "type": "users",
          "id": "15ad7012-b570-48b7-88c1-fbab68be9d05"
        }
      }
    }
  }
}

linkReset heartbeat

Action to reset and stop the machine's heartbeat monitor. This will not deactivate the machine.

linkAuthentication

  • linkBearer

    required

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

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) or URL-safe fingerprint of the machine to reset.

linkReturns

A 200 OK response will be returned along with the reset machine object.

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/reset-heartbeat", {
  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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/reset-heartbeat",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/reset-heartbeat",
  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(
  "machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/reset-heartbeat",
  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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/reset-heartbeat")
  .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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/reset-heartbeat")
  .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("/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/reset-heartbeat");
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 %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/actions/reset-heartbeat \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "9c4c90c8-d4d3-4571-9363-4c7b0332a6a4",
    "type": "machines",
    "links": {
      "self": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4"
    },
    "attributes": {
      "fingerprint": "4d:Eq:UV:D3:XZ:tL:WN:Bz:mA:Eg:E6:Mk:YX:dK:NC",
      "cores": null,
      "ip": null,
      "hostname": null,
      "platform": "macOS",
      "name": "Office MacBook Pro",
      "requireHeartbeat": false,
      "heartbeatStatus": "NOT_STARTED",
      "heartbeatDuration": 600,
      "lastHeartbeat": null,
      "nextHeartbeat": null,
      "metadata": {},
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/product"
        },
        "data": {
          "type": "products",
          "id": "22b78db6-6a2e-4a7f-9369-157976148c4c"
        }
      },
      "license": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/license"
        },
        "data": {
          "type": "licenses",
          "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
        }
      },
      "user": {
        "links": {
          "related": "/v1/accounts/<%= account %>/machines/9c4c90c8-d4d3-4571-9363-4c7b0332a6a4/user"
        },
        "data": {
          "type": "users",
          "id": "15ad7012-b570-48b7-88c1-fbab68be9d05"
        }
      }
    }
  }
}

linkKeys

linkThe key object

Below you will find the various attributes for the key resource, as well as the key resource's relationships. Keys cannot be validated, are not actual "licenses", and are only used for pooled policies.

When creating a pooled policy, you create a limited set of "keys" to fill the pool. Each time a license is created that implements the pooled policy, a "key" is taken from the pool and used for the new license, until the pool is depleted. After a pool has been depleted, new licenses cannot be created from the pooled policy until new keys are added. Pooled policies are usually used for limited betas or promotion deals for the first x users.

These are unused keys within a policy's pool – they are not valid licenses. These are used when creating new licenses for a pooled policy or when using a pool's pop action.

linkAttributes

  • linkkey

    string

    The unique key string for the key.

  • linkcreated

    timestamp (ISO8601 format)read only

    When the key was created.

  • linkupdated

    timestamp (ISO8601 format)read only

    When the key was last updated.

linkRelationships

  • linkaccount

    individual

    The account that the key belongs to.

  • linkproduct

    individual

    The product that the key is associated with.

  • linkpolicy

    individual

    The pooled policy that the key belongs to.

Example object

{
  "data": {
    "id": "6e936a61-94ad-44d1-88ac-88da9f10eca7",
    "type": "keys",
    "links": {
      "self": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7"
    },
    "attributes": {
      "key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/product"
        },
        "data": {
          "type": "products",
          "id": "1f286fb6-c9bb-498b-a4e7-6c67748b1f4f"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/policy"
        },
        "data": {
          "type": "policies",
          "id": "95981290-518b-4109-a611-c0001214b3c5"
        }
      }
    }
  }
}

linkCreate a key

Creates a new key resource.

linkAuthentication

  • linkBearer

    required

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

linkParameters

  • linkaccount

    string, required

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

linkAttributes

  • linkkey

    string, required

    The unique key string for the key. The key cannot collide with license keys that already exist.

linkRelationships

  • linkpolicy

    linkage, required

    The pooled policy the key belongs to.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/keys", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  body: JSON.stringify({
    "data": {
      "type": "keys",
      "attributes": {
        "key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3"
      },
      "relationships": {
        "policy": {
          "data": {
            "type": "policies",
            "id": "4ba02145-d1e7-4443-8104-dd1e4236d869"
          }
        }
      }
    }
  })
})

const { data, errors } = await response.json()
import requests
import json

res = requests.post(
  "https://api.keygen.sh/v1/accounts/<%= account %>/keys",
  headers={
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  },
  data=json.dumps({
    "data": {
      "type": "keys",
      "attributes": {
        "key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3"
      },
      "relationships": {
        "policy": {
          "data": {
            "type": "policies",
            "id": "4ba02145-d1e7-4443-8104-dd1e4236d869"
          }
        }
      }
    }
  })
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/keys",
  method: .post,
  headers: [
    "Content-Type": "application/vnd.api+json",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  ],
  parameters: [
    "data": [
      "type": "keys",
      "attributes": [
        "key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3"
      ],
      "relationships": [
        "policy": [
          "data": [
            "type": "policies",
            "id": "4ba02145-d1e7-4443-8104-dd1e4236d869"
          ]
        ]
      ]
    ]
  ],
  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("keys", 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 = "keys",
    attributes = new {
      key = "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3"
    },
    relationships = new {
      policy = new {
        data = new {
          type = "policies",
          id = "4ba02145-d1e7-4443-8104-dd1e4236d869"
        }
      }
    }
  }
});

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 "keys",
    "attributes" to mapOf(
      "key" to "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3"
    ),
    "relationships" to mapOf(
      "policy" to mapOf(
        "data" to mapOf(
          "type" to "policies",
          "id" to "4ba02145-d1e7-4443-8104-dd1e4236d869"
        )
      )
    )
  )
))

val res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/keys")
  .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", "keys"),
    entry("attributes", ofEntries(
      entry("key", "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3")
    )),
    entry("relationships", ofEntries(
      entry("policy", ofEntries(
        entry("data", ofEntries(
          entry("type", "policies"),
          entry("id", "4ba02145-d1e7-4443-8104-dd1e4236d869")
        ))
      ))
    ))
  ))
));

HttpResponse<JsonNode> res = Unirest.post("https://api.keygen.sh/v1/accounts/<%= account %>/keys")
  .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["key"] = value::string("C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3");

value policy_;
policy_["type"] = value::string("policies");
policy_["id"] = value::string("4ba02145-d1e7-4443-8104-dd1e4236d869");

value policy;
policy["data"] = policy_;

value rels;
rels["policy"] = policy;

value data;
data["type"] = value::string("keys");
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("/keys");
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 %>/keys \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>' \
  -d '{
        "data": {
          "type": "keys",
          "attributes": {
            "key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3"
          },
          "relationships": {
            "policy": {
              "data": {
                "type": "policies",
                "id": "4ba02145-d1e7-4443-8104-dd1e4236d869"
              }
            }
          }
        }
      }'

Example response / 201 Created

{
  "data": {
    "id": "6e936a61-94ad-44d1-88ac-88da9f10eca7",
    "type": "keys",
    "links": {
      "self": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7"
    },
    "attributes": {
      "key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/product"
        },
        "data": {
          "type": "products",
          "id": "1f286fb6-c9bb-498b-a4e7-6c67748b1f4f"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/policy"
        },
        "data": {
          "type": "policies",
          "id": "4ba02145-d1e7-4443-8104-dd1e4236d869"
        }
      }
    }
  }
}

linkRetrieve a key

Retrieves the details of an existing key.

linkAuthentication

  • linkBearer

    required

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

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the key to be retrieved.

linkReturns

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

Definition

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

Example request

const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7", {
  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 %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7",
  headers={
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <%= token %>"
  }
).json()
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7",
  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(
  "keys/6e936a61-94ad-44d1-88ac-88da9f10eca7",
  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 %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7")
  .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 %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7")
  .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("/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7");
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 %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7 \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <%= token %>'

Example response / 200 OK

{
  "data": {
    "id": "6e936a61-94ad-44d1-88ac-88da9f10eca7",
    "type": "keys",
    "links": {
      "self": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7"
    },
    "attributes": {
      "key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
      "created": "<%= created %>",
      "updated": "<%= created %>"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<%= account %>"
        },
        "data": {
          "type": "accounts",
          "id": "<%= account %>"
        }
      },
      "product": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/product"
        },
        "data": {
          "type": "products",
          "id": "1f286fb6-c9bb-498b-a4e7-6c67748b1f4f"
        }
      },
      "policy": {
        "links": {
          "related": "/v1/accounts/<%= account %>/keys/6e936a61-94ad-44d1-88ac-88da9f10eca7/policy"
        },
        "data": {
          "type": "policies",
          "id": "95981290-518b-4109-a611-c0001214b3c5"
        }
      }
    }
  }
}

linkUpdate a key

Updates the specified key 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.

linkParameters

  • linkaccount

    string, required

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

  • linkid

    string, required

    The identifier (UUID) of the key to be updated.

linkAttributes