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