Select programming language for code examples

linkAuthentication

Most API requests will require a form authentication. Access to resources will depend on the requestor's authorization level. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. Most API requests without authentication will also fail.

Below we'll dig into the different ways that you can authenticate with Keygen's API.

linkLicense Key Authentication

The first way to authenticate, and arguably the simplest way, is by authenticating with a license's key. Authenticating with a license key is essentially the same as authenticating with a license token (formerly known as an activation token).

License key authentication can only be utilized if the license policy's authentication strategy is set to LICENSE or MIXED. Otherwise, you will receive a forbidden error response.

License keys should be specified within the Authorization request header, using the License authorization scheme. This scheme is required, otherwise it will assumed to be an API token and the request will fail with a TOKEN_INVALID error response.

Authorization: License <key>

Alternatively, a license key may also be provided in the following ways:

  • By using the Basic authentication scheme: license:<key>
  • By using the auth query parameter: ?auth=license:<key>

You can utilize license key authentication to perform client-side machine activation and deactivation, as well as other actions, such as sending heartbeat pings.

Typically, license key authentication is meant to be used client-side.

Obtaining a license ID using a key

For many requests, such as machine activation, you will need to provide a license relationship for the machine. This relationship will need to match the license making the request. And you won't be able to use the license key here — this will require the license's ID.

You can obtain your license's ID by using the whoami endpoint, or by validating the license key, both of which will include the license object in the response payload.

Expirations and suspensions

When a license has expired, API access depends on the policy's expiration strategy. When the strategy is set to RESTRICT_ACCESS, then the request will be allowed. When it's set to REVOKE_ACCESS, the request will fail with a 403 forbidden error response.

When a license has been suspended, they will no longer be able to authenticate with the API. Requests will fail with a 403 forbidden error response.

Limitations

The maximum acceptable length of an HTTP header is 8KB. Please ensure that your license key fits within that size limitation, otherwise your request fail. This is especially important when using signed keys, since these have the potential to be very large.

Example license key authentication

curl -X POST https://api.keygen.sh/v1/accounts/demo/machines \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: License C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3' \
-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"
}
}
}
}
}'

linkToken Authentication

The next way to authenticate is through API tokens. There are a few different token types, and each carry their own unique permission set.

Tokens should be specified within the Authorization request header. You may use a Bearer or Token authorization scheme.

Authorization: Bearer <token>

Alternatively, a token may also be provided in the following ways:

  • By using the Basic authentication scheme: token:<token>
  • By using the auth query parameter: ?auth=token:<token>

When a token has expired, the request will fail with a 401 unauthorized error response. You are recommended to use the 401 HTTP status code to automatically log the user out (or otherwise clear the session).

Product Tokens

Product tokens are for server-side integrations. A product token allows full management of a products resources. For example, a product token can create new licenses, or create a new product release. It can also delete licenses and machines. By default, a product token does not expire, though this can be adjusted during token creation.

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

You can generate a product using using the product's tokens relationship.

Use Cases

  • Generate a license after a successful payment has been made.
  • Suspend a license after a subscription has been canceled.
  • Integrating Keygen entirely server-side.

License Tokens

License tokens, also called activation tokens, are specific to an individual license. In a nutshell — these tokens allow a license to activate and deactivate their machines. A license token can also do other actions, like validate the license or issue a heartbeat ping for any of their machines. By default, a license token does not expire, though this can be adjusted during token creation.

A license can only manage and view its own resources.

License tokens can only be utilized if the license policy's authentication strategy is set to TOKEN or MIXED. Otherwise, you will receive a forbidden error response.

You can generate a license token using the license's tokens relationship.

Use Cases

  • Perform client-side machine activation and deactivation.
  • Perform client-side machine heartbeat pings.
  • Perform client-side license validation.

User Tokens

User tokens are personal — specific to an individual user and their role. Depending on your account settings, a user can do things such as activate and deactivate machines, or even create new licenses for themselves. By default, a user token expires after 2 weeks, though this can be adjusted during token creation.

A user can only manage and view their own resources.

When allowing a user to perform certain actions, such as license creation, we recommend listening for webhook events so that you can appropriately handle billing.

You can generate a user token using the tokens resource, or via the user's token relationship.

Use Cases

  • Allow a user to login using email and password, rather than a license key.
  • Allow a user to have multiple licenses associated with a single profile.
  • Allow a user to self-manage their resources client-side.

Example token authentication

curl -X POST https://api.keygen.sh/v1/accounts/demo/machines \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer lic-6171564a4a59e5f3879c0584ebe92ce3v3' \
-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"
}
}
}
}
}'