menu
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 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 or ALLOW_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).

Environment Tokens

Environment tokens are for server-side integrations. An environment token allows near-full management of an environment's resources. For example, an environment token can create new licenses and machines in its environment. By default, an environment 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 and the token type, so be sure to keep them secret! Do not share your admin, environment 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 an environment token using using the environment's tokens relationship.

Use Cases

  • Manage resources in an isolated sandbox or production environment.
  • Generate a license for a specific environment.
  • List releases for a specific environment.
  • Integrating Keygen entirely server-side.

Product Tokens

Product tokens are also for server-side integrations. A product token allows full management of a product's resources. For example, a product token can create new licenses for itself, or create new product releases and artifacts. It can also delete licenses and other resources it owns. 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 and the token type, so be sure to keep them secret! Do not share your admin, environment 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 token 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 formerly 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.

By default, users are allowed to perform actions you may not want, such as license creation, machine management, and more. Please review the user permissions for more information. You can limit what actions a user can perform by customizing their permissions (available on Ent tiers only), or by setting the account, policies, and/or licenses to protected.
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.

Admin Tokens

Admin tokens are used for Dashboard sessions. An admin token allows full management of a Keygen account's resources. For example, an admin token can create new admins, can create new products, policies, and licenses, and can also create new releases. It can also delete and modify all of these things.

Admin tokens SHOULD NOT be utilized for an API integration. These tokens are only meant to be used by our Dashboard, not for API integrations.

Why? Because an admin's tokens are automatically revoked when the admin's password is changed, when its second factors are changed, or when the admin's role or permissions are changed. As such, we DO NOT recommend using admin tokens for an API integration. Doing so could cause your API integration to break unexpectedly.

Use Cases

  • For the Dashboard.
  • See addendum.

Addendum

With the above risks understood concerning auto-revocation, they HAVE been used for server-side integrations to manage multiple products. To do so, an admin token will need to be generated using the API token generation endpoint.

But we DO NOT recommend this.

As an alternative to admin tokens, we recommend using environment tokens. These are scoped to a particular environment, e.g. production, staging, or dev.

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"
              }
            }
          }
        }
      }'