Website monitor keygen

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 Getting 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 that you chose during sign up. Every API request will utilize your account's ID or slug within the URL path, i.e. or . Your account's ID and slug can be used interchangably as URL params.

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 % 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 header:

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

By default our API will respond with , unless asked otherwise through the standard HTTP header. All other content types will be rejected with a 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.

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.

Alternative HTTP Libraries

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

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.

When we introduce breaking changes to the API, we will release a new numbered version, e.g. we will go from to . The current version is . 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.

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

1. Do not store your API tokens in version control. If you're using version control like Git or Subversion, do not store your API tokens in version control. It is recommended that you store tokens in a file that is never checked into the repository, or within the .

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

2. Do not embed your admin or product API tokens within your product's source 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.

   Instead, you can perform license and machine creation requests client-side while authenticated as one of your users and then you can listen for the corresponding webhook events to act accordingly e.g., charging them for new licenses, crediting them for deleted licenses or machines, etc. For an example of responding to user actions, see our Paddle integration example.

   If you're using Keygen server-side, see the above tip.

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

4. Embedding account, product and policy IDs directly into your product i.e. client-side code is perfectly safe. In fact, you won't be able to communicate with Keygen's API unless you do so, 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.

5. 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 , 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 (which by default is inherited from the account's current 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 , which will disallow machine activation/deactivation; similar to policies, the license's attribute is inherited from its policy.

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

6. To validate license keys offline, you can cryptographically sign or encrypt license keys. To enable this feature, you choose an appropriate when creating a new policy. Each will behave differently, so be sure that you understand how to implement and verify the one you choose. Reach out to our support channels if you have any questions.

   Alternatively, you can set up "air-gapped" license activation using TOTP, QR codes, and a mobile device. View our example implementation.

   Please note that offline license validation is, of course, quite limited in what can be enforced. E.g. to validate against a license's machine requirements would require an internet connection. Keep that in mind.

7. If you only need to validate license keys, then you do not need to implement user authentication. The license 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 activation tokens will be required in order to communicate with Keygen's API 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.

Our API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the range indicate success, codes in the 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 range indicate an error with our servers (these are rare).

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.

• linkmanicapital.comr

  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.

• linkmanicapital.comter

  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

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

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

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.

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

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

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

A single IP address can make a maximum burst of 60 requests per 30 second window and requests per 5 minute window, which allows for 1 request/sec with short bursts of up to requests/sec, regardless of authentication. We may add additional rate limit windows in the future, which will be included within the header with a specific name, e.g. .

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.

When rate limited, a 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:

Example response / Too Many Requests

Throughout the API, many resources will have a 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 for short.

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

Example resource identifier object

Many resources including products, users, licenses, machines and policies have a 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 within your own database (if applicable), or their Stripe for billing purposes.

Since the 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.

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

Key Transformation

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

Example Use Cases

Here's a few example use cases:

Example request

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 query parameter.

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

linkParameters

• linkpage

  hash<string, integer>

  Hash containing page size and page number.

• linkmanicapital.com

  integer

  The page size. Must be a number between 1 and

• linkmanicapital.com

  integer

  The page number.

Example request

Example response

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 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) and ignoring future webhook events that come through with an identical token, signaling a retried event.

Example resource

A failed webhook event resource.

Example request

Retry the above failed webhook event resource.

Example response

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

Each Keygen account is equipped with its own unique RSA bit public/private keypair, which is used in signing response payloads using RSA-SHA, and which can also be used to sign or encrypt license keys for 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 response payloads and license keys. Private keys are kept securely encrypted on our servers.

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.

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 cryptography section and the different policy schemes available.

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

Example Python cryptographic verification

linkRequest Signatures

Request signature verification is useful for verifying requests came from Keygen, 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.

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

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.

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

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 string is hashed before being stored in our databases, thus is only available directly after generating/regenerating a token.

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 (ISO 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 (ISO format)read only

  When the token was created.

• linkupdated

  timestamp (ISO 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

linkGenerate a token

Generate a new token resource for a user. To generate a token for a product, see the product 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.

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 (ISO format), optional

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

linkReturns

Definition

Example request

Example response / Created