linkAuthentication

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 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>
Authorization: License <key>
content_copy

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.

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>
Authorization: Bearer <token>
content_copy

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.

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.

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 called license 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.

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.

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.

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.