linkKeygen Dist

The Keygen Dist API is a hosted distribution server for your Keygen products. All requests must be made over TLS/SSL. In addition, all request and response bodies, including errors, are encoded in JSON format, with the exception of delivering actual release files which are delivered as raw files (i.e. the content type will be determined from the uploaded file).

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.

linkPre-populated Examples

Your authentication token is pre-populated in all the examples on this page if you're currently logged in to your dashboard, so you can test any example right away. Only you can see these values.

The pre-populated token is an admin token and is not meant to be used in client-facing code, stored in version control, and so forth. Read more on security.

linkAPI Versioning

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

Keep in mind that stable does not mean complete. We could potentially add new endpoints, but existing endpoints will remain unchanged.

linkBackwards Compatibility

What do we consider to be “backwards-compatible” changes?

  • Adding new API endpoints
  • Adding new optional request parameters to existing API endpoints

linkLicense Validation

A valid license key must be specified for every request. The request will be rejected for licenses that do not pass validation, and an error will be returned detailing the reason for the validation failure. The only exception to this is when you provide an admin authorization token.

If your policy requires certain validation scopes, these will be required. For example, if the license's policy requires a machine fingerprint scope, you must provide a fingerprint query parameter. Otherwise, the request will be rejected.

linkErrors

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.

  • linksource.pointer

    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.

  • linksource.parameter

    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

{
  "errors": [
    {
      "title": "Unauthorized",
      "detail": "License fingerprint scope is required"
    }
  ]
}

linkDistribution

linkLicense-Gated Access

All releases are gated with license validation; meaning, when providing download URLs to your users, you must provide a valid license key within the request or the request will be rejected. We essentially act as a license-gated static file storage system, backed by AWS S3.

For example, you may choose to email the user a download link after they purchase your product. You should include their new license key as a query parameter within the URL, or generate a temporary download link.

Access to releases and updates will remain accessible for as long as a license is valid. If the license becomes invalid, e.g. it expires or is suspended, it will no longer be allowed to access releases.

For some licensing models e.g. one which requires a machine fingerprint scope, this may introduce a catch-22, where a license needs a machine associated with it for the download to be allowed, but at the same time the product needs to be downloaded to be able to perform a machine activation (i.e. you need access to the machine's MAC address, etc. to fingerprint the device).

In these situations, you can generate a temporary download link for the customer to utilize for the initial download request. These download links have a limited time-to-live (TTL).

Example License-gated Release URL

https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/latest/macos/dmg?key=bbec-988f-b52f-5188

linkAuto Updates

The update endpoint is compatible with Squirrel.Mac, NSIS, Sparkle, WordPress for plugin and theme updates, as well as any other auto-update system or framework that needs to determine if an update is available from the current version number.

Please be to sure to include a license key for update requests, otherwise the request will be rejected.

linkNotes for Squirrel.Windows

When uploading releases for Squirrel.Windows, please ensure that the release files within your RELEASES file are relative paths, not URLs. Keygen Dist will automatically rewrite your release file paths to include the provided licensing information (passed via query parameters).

For example, given a RELEASES file like below,

0XFF… your-app-1.0.0-full.nupkg 0123
0XFF… your-app-2.0.0-delta.nupkg 0123
0XFF… your-app-2.0.0-full.nupkg 0123

When requested like so,

GET https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/win32/RELEASES?key=foobar

The RELEASES file's contents will automatically be rewritten to,

0XFF… https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/win32/your-app-1.0.0-full.nupkg?key=foobar 0123
0XFF… https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/win32/your-app-2.0.0-delta.nupkg?key=foobar 0123
0XFF… https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/win32/your-app-2.0.0-full.nupkg?key=foobar 0123

If you wish to opt out of the rewrite behavior, you may supply URLs instead of paths for your release files. For example,

0XFF… https://dist.example.com/download/win32/your-app-1.0.0-full.nupkg 0123
0XFF… https://dist.example.com/download/win32/your-app-2.0.0-delta.nupkg 0123
0XFF… https://dist.example.com/download/win32/your-app-2.0.0-full.nupkg 0123
Please be aware that there is a 5MB transfer limit for any RELEASES file. This should not be an issue given a plaintext RELEASES file (which is what it should be), but you may not receive the entire file if it is of another filetype e.g. a zip file, binary file, etc.

linkNotes for electron-builder

Unlike Electron's native auto-updater, electron-builder does not utilize a normal Squirrel release server. Because of this, electron-builder's auto-updater, electron-updater, will not utilize the /update endpoint. Rather, you will utilize the /releases endpoint for all platforms. In this way, Keygen Dist will act as a license-gated static file store.

Your feedURL should look something like this:

https://dist.keygen.sh/v1/${accountId}/${productId}/releases/${platform}?key=${licenseKey}

How electron-updater performs an update is like this:

  1. For macOS, it will request latest-mac.yml from the release server. For Windows, it will request RELEASES. It does so by appending either /latest-mac.yml or /RELEASES to the feedURL path.
  2. It will check the latest version in the returned file against the the current version of the app.
  3. It will request the newer version if one is available.

Using the electron-builder code example, and assuming we're on the macos platform, electron-updater will automatically use the above feedURL as a "base URL" to request the following latest-mac.yml file, as explained above:

https://dist.keygen.sh/v1/${accountId}/${productId}/releases/${platform}/latest-mac.yml?key=${licenseKey}

That yml file will then be downloaded and read, and then used to request the latest app version, if there is one available. It will use similar logic to request the app version, by appending the version to the feedURL path.

linkOther Examples

If you'd like to see examples for another framework or in another language, please let us know.

Example Using Electron's Native Auto-Updater

If you're using electron-builder, please see the other example below.

const { app, autoUpdater } = require('electron')
const { platform } = process

const licenseKey = getLicenseKeyForCurrentUser()
const version = app.getVersion()

const distUrl = `https://dist.keygen.sh/v1/${KEYGEN_ACCOUNT_ID}/${KEYGEN_PRODUCT_ID}`
let feedUrl

switch (platform) {
  case 'darwin': // Squirrel.Mac expects a JSON response pointing to the newest version (if available)
    feedUrl = `${distUrl}/update/${platform}/zip/${version}?key=${licenseKey}`
    break
  case 'win32': // Squirrel.Windows expects a base URL which it will use to request your RELEASES file
    feedUrl = `${distUrl}/releases/${platform}?key=${licenseKey}`
    break
}

if (feedUrl) {
  autoUpdater.setFeedURL(feedUrl)
  autoUpdater.checkForUpdates()
}

Example Using electron-builder's Auto-Updater

const { autoUpdater } = require('electron-updater')
const { platform } = process
const licenseKey = getLicenseKeyForCurrentUser()

autoUpdater.setFeedURL({
  url: `https://dist.keygen.sh/v1/${accountId}/${productId}/releases/${platform}?key=${licenseKey}`,
  useMultipleRangeRequest: false, // Our service does not support this
  provider: 'generic',
  channel: 'latest'
})

linkProxy Server

If you would rather deliver releases behind your own domain, you can run a proxy server. We have an example Node.js proxy server available for reference which utilizes this API.

The Node.js proxy server supports the following endpoints:

linkStorage

Each release has a "platform" and a "key" (i.e. the release's filename and path). Release keys uniquely identify a release for a particular platform. The "platform" is a way to scope like-named releases i.e. windows/v1.3.zip and macos/v1.3.zip to avoid collisions, and to keep things tidy.

linkFlat File-System

Note that the Keygen Dist file-system is a flat structure: you can create releases for any "platform" and may use keys that include the "/" delimiter (commonly used within file paths), but there is no actual hierarchy of sub-directories

You can infer logical hierarchy using key "prefixes" and the "/" delimiter to give the illusion and functionality of a file-system with sub-directories for maximum compatibility with distribution systems which rely on a particular hierarchy e.g., Squirrel.Windows, Sparkle, RubyGems, or Composer.

For example, the following are all valid release keys (including the platform for clarity):

win32/Releases/MyApp-1.0.0-full.nupkg
win32/Releases/MyApp-1.1.0-full.nupkg
win32/Releases/MyApp-1.1.0-delta.nupkg
win32/Releases/Setup.exe
win32/Releases/Setup.msi
win32/Releases/RELEASES
darwin/.notes/CHANGELOG.md
darwin/v1.0.0.zip
darwin/v1.0.0.dmg
darwin/v1.1.0.zip
darwin/v1.1.0.dmg

Note that the releases for the darwin platform are all placed within the root "directory", while the releases for the win32 platform use a sub-directory hierarchy. The above releases are accessible at the following URIs:

/v1/{ACCOUNT}/{PRODUCT}/win32/Releases/MyApp-1.0.0-full.nupkg
/v1/{ACCOUNT}/{PRODUCT}/win32/Releases/MyApp-1.1.0-full.nupkg
/v1/{ACCOUNT}/{PRODUCT}/win32/Releases/MyApp-1.1.0-delta.nupkg
/v1/{ACCOUNT}/{PRODUCT}/win32/Releases/Setup.exe
/v1/{ACCOUNT}/{PRODUCT}/win32/Releases/Setup.msi
/v1/{ACCOUNT}/{PRODUCT}/win32/Releases/RELEASES
/v1/{ACCOUNT}/{PRODUCT}/darwin/.notes/CHANGELOG.md
/v1/{ACCOUNT}/{PRODUCT}/darwin/v1.0.0.zip
/v1/{ACCOUNT}/{PRODUCT}/darwin/v1.0.0.dmg
/v1/{ACCOUNT}/{PRODUCT}/darwin/v1.1.0.zip
/v1/{ACCOUNT}/{PRODUCT}/darwin/v1.1.0.dmg

But the following URIs are not accessible (because e.g. a release with the key Releases does not exist, as our file-system is flat i.e. it has no concept of "sub-directories" or partial key matches):

/v1/{ACCOUNT}/{PRODUCT}/win32/Releases
/v1/{ACCOUNT}/{PRODUCT}/darwin/.notes

linkSafe Characters

The following character sets are generally safe for use in release keys:

  • Alphanumeric characters: [0-9a-zA-Z]
  • Special characters: /, !, -, _, ., *, ', (, and )

And the following characters are not safe for use (or iffy at best):

  • Restricted characters: " " (space character), %, ?, &, and other non-URL friendly characters

Please be sure to follow these guidelines, as while your links may work for one platform, it may not work on another if you choose to deviate into using any restricted characters.

linkChecksums

Each release has a checksum attribute, which may be calculated differently depending on file size, as well as the upload method used. Each checksum may have up to 2 parts, separated by a dash.

The first part is the actual checksum and the second part indicates in how many parts the file was split during transfer.

When downloading a release, you can also obtain the file's checksum through the Content-Checksum header. The header value will be the file's base64 encoded checksum value.

linkChecksum Calculation

To calculate the first part you have to make a list of MD5 hashes of all the parts, convert it into binary format and take the MD5 hash of it. Afterwards you append a dash and add the number of parts you've split your file into.

For example, the following checksum was constructed from an MD5 hash of 4 separate parts' MD5 hash, then appended with a -4 to indicate the number of parts the file was split into.

c3b6303207d30de3dbb228b5ba94c31f-4

To construct the MD5 hash, you will read the file 8MB at a time (8 * 1024 * 1024 bytes), hashing each part that is read using MD5. Once all parts have been hashed, concatenate all of the hashes, and hash that value also using MD5. Append the hash count at the end, separated by a dash, and you should have a matching checksum value.

If there is no dash included within the checksum, it will simply be the MD5 hash of the entire file's contents. This is likely the case for small files or for files uploaded within a single request.

Example Python Checksum CLI

#!/usr/bin/env python

import hashlib
import sys

def calculate_checksum(file_path, parts, chunk_size = 8 * 1024 * 1024):
  md5s = []

  with open(file_path, 'rb') as fp:
    while True:
      data = None

      if parts > 1:
        data = fp.read(chunk_size)
      else:
        data = fp.read()

      if not data:
        break

      md5s.append(hashlib.md5(data))

  if len(md5s) == 1:
    return '{}'.format(md5s[0].hexdigest())

  digests = b''.join(m.digest() for m in md5s)
  digests_md5 = hashlib.md5(digests)

  return '{}-{}'.format(
    digests_md5.hexdigest(),
    len(md5s)
  )

file_path = sys.argv[1]
parts = 1
if len(sys.argv) == 3:
  parts = int(sys.argv[2])

print(
  calculate_checksum(file_path, parts)
)

Example Python CLI Usage

./checksum.py /path/to/file 4
# => c3b6303207d30de3dbb228b5ba94c31f-4

linkSemantic Versioning

Semantic Versioning (SemVer) naming conventions are required in order to utilize certain endpoints. This is because there is no way for us to support arbitrary version naming conventions, so we have chosen to only support SemVer. All SemVer release files must reside within the top-level root directory /; releases within sub-directories will not be used.

SemVer release keys may not contain any prefixes/suffixes, aside from a file extension, e.g. Cool Product-1.3.0-macOS.dmg, /directory/1.4.dmg; the filename must only contain the version, with an optional v prefix e.g. v1.0.zip, 2.3.19.zip, etc.

The following endpoints require these conventions:

But please note that these restrictions are scoped per-platform and file-extension, so you may e.g. choose to use SemVer for your macOS releases in order to support updates using Squirrel.Mac, but not use SemVer naming conventions for your Windows releases in order to support the file structure required for providing updates using Squirrel.Windows.

linkPlatforms

linkThe platform object

Below you will find the various attributes for the platform resource.

linkAttributes

  • linkname

    string

    The platform name.

Example object

{
  "data": {
    "type": "platforms",
    "id": "ebaa3498-0202-40d8-1908-ab208c075806",
    "attributes": {
      "name": "windows"
    }
  }
}

linkList platforms

List all platforms for the given product.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product.

linkParameters

  • linkaccount

    string, required

    The identifier (UUID) of your Keygen account.

  • linkproduct

    string, required

    The identifier (UUID) of the product the release is for.

  • linkplatform

    string, required

    The platform name.

linkReturns

A list of all platforms for the given product along with a 200 OK status.

Definition

https://dist.keygen.sh/v1/{ACCOUNT}/{PRODUCT}/platforms

Example requests

curl https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/platforms \
  -H "Authorization: Bearer <%= token %>"

Example response / 200 OK

{
  "data": [
    {
      "type": "platforms",
      "id": "d8bfff5d-fce3-408b-4759-aae8d06d0108",
      "attributes": {
        "name": "linux"
      }
    },
    …
  ]
}

linkDownload Links

linkGenerate a download link

Generate a temporary signed URL to that can be used to download the release via a GET request. The URL will expire after the specified TTL, in seconds. The default TTL is 1 week, or 604800 seconds.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product.

linkParameters

  • linkaccount

    string, required

    The identifier (UUID) of your Keygen account.

  • linkproduct

    string, required

    The identifier (UUID) of the product the release is for.

  • linkplatform

    string, required

    The platform the release belongs to.

  • linkrelease

    string, required

    The key i.e. path and filename of the release to download.

linkQuery Parameters

  • linkttl

    integer, default is604800

    The time, in seconds, that the URL will be valid for.

linkReturns

Upon successful link generation, the request will respond with 307 Temporary Redirect. If the release does not exist, a 404 Not Found will be given.

When an Accept: application/json header is included in an upload request, a 200 OK response will be returned instead of a 307 Temporary Redirect.

Definition

https://dist.keygen.sh/v1/{ACCOUNT}/{PRODUCT}/download/{PLATFORM}/{RELEASE}

Example request

curl -v -X POST https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/download/macos/v1.0.0.zip?ttl=60 \
  -H "Authorization: Bearer <%= token %>"

Example response / 307 Temporary Redirect

Location: https://keygen-dist.s3.us-east-2.amazonaws.com/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.0.0.zip{
  "url": "https://keygen-dist.s3.us-east-2.amazonaws.com/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.0.0.zip",
  "name": "v1.0.0.zip"
}

linkReleases

linkThe release object

Below you will find the various attributes for the release resource. Accessing a release directly i.e. a release's url will download the actual release file that was uploaded.

linkAttributes

  • linkurl

    string

    The URL to download the release.

  • linkkey

    string

    The key i.e. filename and path for the release.

  • linkplatform

    string

    The platform the release is for.

  • linkchecksum

    string

    The checksum of the release. See the checksum topic for more information.

  • linkfilesize

    integer

    The size of the release in bytes.

Example object

{
  "data": {
    "type": "releases",
    "id": "90afc0d2-7343-40f8-abdd-07aed3d6d22b",
    "attributes": {
      "url": "https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/1.9.1.zip",
      "checksum": "487fa2f58bc9ada4dc90e0b3c781f1b5",
      "filesize": 45095551,
      "key": "1.9.1.zip",
      "platform": "macos"
    }
  }
}

linkUpload a release

Create and upload a new release. This will overwrite any release that already exists that shares the same destination. In addition to creating releases through the Keygen Dist API, you can also manage releases for your products from your admin dashboard. Simply navigate to a product page and upload your releases using the provided form.

This endpoint has a max filesize of 100MB. For releases that are larger than 100MB, please use the direct upload endpoint.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product.

linkParameters

  • linkaccount

    string, required

    The identifier (UUID) of your Keygen account.

  • linkproduct

    string, required

    The identifier (UUID) of the product the release is for.

  • linkplatform

    string, required

    The platform the release is for. This can be an arbitrary string.

  • linkrelease

    string, required

    The key i.e. path and filename of the new release. This may include one or more "sub-directories".

linkReturns

Upon successful upload, the request will respond with 204 No Content. If the file is too large, a 413 Request Entity Too Large will be given.

Definition

https://dist.keygen.sh/v1/{ACCOUNT}/{PRODUCT}/releases/{PLATFORM}/{RELEASE}

Example request

curl -vf -X PUT https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.0.0.zip \
  -H "Authorization: Bearer <%= token %>" \
  -F "[email protected]/v1.0.0.zip"

Example response / 204 No Content

No content

linkUploading large releases

Generate a signed URL to upload large files directly to our storage provider. The URL will expire after 60 seconds.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product.

linkParameters

  • linkaccount

    string, required

    The identifier (UUID) of your Keygen account.

  • linkproduct

    string, required

    The identifier (UUID) of the product the release is for.

  • linkplatform

    string, required

    The platform the release is for. This can be an arbitrary string.

  • linkrelease

    string, required

    The key i.e. path and filename of the new release. This may include one or more "sub-directories".

linkReturns

Upon success, the request will respond with a 307 Temporary Redirect status, along with a Location header. You can then upload the large file by performing a PUT request to the given location. You should upload the binary data directly, i.e. do not send multipart/form-data - the request body will be stored as-is.

When an Accept: application/json header is included in an upload request, a 200 OK response will be returned instead of a 307 Temporary Redirect.

Definition

https://dist.keygen.sh/v1/{ACCOUNT}/{PRODUCT}/releases/{PLATFORM}/{RELEASE}

Example request

curl -vf -X POST https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.0.0.zip \
  -H "Authorization: Bearer <%= token %>"

Example response / 307 Temporary Redirect

Location: https://keygen-dist.s3.us-east-2.amazonaws.com/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.0.0.zip{
  "url": "https://keygen-dist.s3.us-east-2.amazonaws.com/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.0.0.zip",
  "name": "v1.0.0.zip"
}

Example request

curl -vfg -X PUT "https://keygen-dist.s3.us-east-2.amazonaws.com/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.0.0.zip" \
  -T "dist/v1.0.0.zip"

linkDelete a release

Permanently delete a release. It cannot be undone. All existing download links for the release will cease to function.

linkAuthentication

  • linkBearer

    required

    An authentication token with privileges to manage the resource: either an admin or the product.

linkParameters

  • linkaccount

    string, required

    The identifier (UUID) of your Keygen account.

  • linkproduct

    string, required

    The identifier (UUID) of the product the release is for.

  • linkplatform

    string, required

    The platform the release belongs to.

  • linkrelease

    string, required

    The key i.e. path and filename of the release to delete.

linkReturns

Upon successful deletion, the request will respond with 204 No Content.

Definition

https://dist.keygen.sh/v1/{ACCOUNT}/{PRODUCT}/releases/{PLATFORM}/{RELEASE}

Example request

curl -vf -X DELETE https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/windows/v1.0.0.zip \
  -H "Authorization: Bearer <%= token %>"

Example response / 204 No Content

No content

linkList releases

List all releases for the given product. A valid license key must be specified to list releases. The request will be rejected for licenses that do not pass validation, and an error will be returned detailing the reason for the validation failure.

linkAuthentication

  • linkBearer

    To bypass license validation, an authentication token with privileges to manage the resource may be supplied; either an admin or a token that belongs to the product. If a bearer token is not supplied, at a minimum a license key is required to process the request.

  • linkBasic

    Instead of supplying a license key and an optional machine fingerprint as query parameters, you may supply a license key and an optional machine fingerprint as the username and password, respectively, via basic authentication. This is useful for distribution methods that do not accept query parameters, for example, a Rubygems server. Note that when using this method, the license key cannot contain the ':' character.

linkParameters

  • linkaccount

    string, required

    The identifier (UUID) of your Keygen account.

  • linkproduct

    string, required

    The identifier (UUID) of the product the release is for.

  • linkplatform

    string, required

    The platform to scope releases to.

linkQuery Parameters

  • linkkey

    string, required

    The license key to validate. Please note: this must be the license's key attribute, not its ID.

  • linkfingerprint

    string, optional

    The machine fingerprint to scope the license validation to.

  • linkmachine

    string, optional

    The machine identifier (UUID) to scope the license validation to.

  • linkpolicy

    string, optional

    The policy identifier (UUID) to scope the license validation to.

linkReturns

A list of all releases for the given product along with a 200 OK status.

Definition

https://dist.keygen.sh/v1/{ACCOUNT}/{PRODUCT}/releases/{PLATFORM}

Example requests

# Using bearer authentication
curl -vf https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/linux \
  -H "Authorization: Bearer <%= token %>"

# Using basic authentication
curl -vf https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/linux \
  -u "bbec-988f-b52f-5188:"

# Using query parameters
curl -vf https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/linux?key=bbec-988f-b52f-5188

# or…
curl -vf -G https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/linux \
  -d "key=bbec-988f-b52f-5188"

Example response / 200 OK

{
  "data": [
    {
      "type": "releases",
      "id": "90afc0d2-7343-40f8-abdd-07aed3d6d22b",
      "attributes": {
        "url": "https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/linux/1.9.1.zip",
        "checksum": "6f5902ac237024bdd0c176cb93063dc4",
        "filesize": 41082597,
        "key": "1.9.1.zip",
        "platform": "linux"
      }
    },
    …
  ]
}

linkDownload a release

Download a release. A valid license key must be specified to download a release. The download request will be rejected for licenses that do not pass validation, and an error will be returned detailing the reason for the validation failure.

The download endpoint accepts an optional byte Range header, which will supply a specified content range. We do not support multipart range requests at this time.

linkAuthentication

  • linkBearer

    To bypass license validation, an authentication token with privileges to manage the resource may be supplied; either an admin or a token that belongs to the product. If a bearer token is not supplied, at a minimum a license key is required to process the request.

  • linkBasic

    Instead of supplying a license key and an optional machine fingerprint as query parameters, you may supply a license key and an optional machine fingerprint as the username and password, respectively, via basic authentication. This is useful for distribution methods that do not accept query parameters, for example, a Rubygems server. Note that when using this method, the license key cannot contain the ':' character.

linkParameters

  • linkaccount

    string, required

    The identifier (UUID) of your Keygen account.

  • linkproduct

    string, required

    The identifier (UUID) of the product the release is for.

  • linkplatform

    string, required

    The platform the release belongs to.

  • linkrelease

    string, required

    The key i.e. path and filename of the release to download.

linkQuery Parameters

  • linkkey

    string, required

    The license key to validate. Please note: this must be the license's key attribute, not its ID.

  • linkfingerprint

    string, optional

    The machine fingerprint to scope the license validation to.

  • linkmachine

    string, optional

    The machine identifier (UUID) to scope the license validation to.

  • linkpolicy

    string, optional

    The policy identifier (UUID) to scope the license validation to.

  • linkchecksum

    string, optional

    The expected integrity checksum.

linkReturns

A 200 OK, or a 206 Partial Content for range requests, status will be returned along with the requested release content.

Definition

https://dist.keygen.sh/v1/{ACCOUNT}/{PRODUCT}/releases/{PLATFORM}/{RELEASE}

Example requests

# Using bearer authentication
curl -vf https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.0.0.zip \
  -H "Authorization: Bearer <%= token %>" \
  -o "v1.0.0.zip"

# Using basic authentication
curl -vf https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.0.0.zip \
  -u "bbec-988f-b52f-5188:" \
  -o "v1.0.0.zip"

# Using query parameters
curl -vf https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.0.0.zip?key=bbec-988f-b52f-5188 \
  -o "v1.0.0.zip"

# or…
curl -vf -G https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.0.0.zip \
  -d "key=bbec-988f-b52f-5188" \
  -o "v1.0.0.zip"

Example response / 200 OK

The requested release

linkDownload an update

Download an update. A valid license key must be specified to download an update. The download request will be rejected for licenses that do not pass validation, and an error will be returned detailing the reason for the validation failure. This endpoint will only look in the top-level root directory / for releases files.

In order to utilize this endpoint, all release keys must follow SemVer for the requested file extension. If any release key does not follow SemVer naming conventions, the update request will fail with a 422 error.

linkAuthentication

  • linkBearer

    To bypass license validation, an authentication token with privileges to manage the resource may be supplied; either an admin or a token that belongs to the product. If a bearer token is not supplied, at a minimum a license key is required to process the request.

  • linkBasic

    Instead of supplying a license key and an optional machine fingerprint as query parameters, you may supply a license key and an optional machine fingerprint as the username and password, respectively, via basic authentication. This is useful for distribution methods that do not accept query parameters, for example, a Rubygems server. Note that when using this method, the license key cannot contain the ':' character.

linkParameters

  • linkaccount

    string, required

    The identifier (UUID) of your Keygen account.

  • linkproduct

    string, required

    The identifier (UUID) of the product the release is for.

  • linkplatform

    string, required

    The platform to scope updates to.

  • linkextension

    string, required

    The file extension to use e.g. zip, dmg, nupkg, tgz, etc.

  • linkversion

    string, required

    The SemVer-compatible version string to check against i.e. the user's current version of the product.

linkQuery Parameters

  • linkkey

    string, required

    The license key to validate. Please note: this must be the license's key attribute, not its ID.

  • linkchannel

    string, optional, default isstable

    The release channel. One of: stable or prerelease. The prerelease channel will include release candidates, as well as alpha/beta versions.

  • linkfingerprint

    string, optional

    The machine fingerprint to scope the license validation to.

  • linkmachine

    string, optional

    The machine identifier (UUID) to scope the license validation to.

  • linkpolicy

    string, optional

    The policy identifier (UUID) to scope the license validation to.

linkReturns

If an update is available, a 307 Temporary Redirect will be returned pointing to the latest update release. Otherwise, 204 No Content will be returned.

For compatibility with Squirrel.Mac, when an Accept: application/json header is included in an update request, a 200 OK response will be returned instead of a 307 Temporary Redirect.

Definition

https://dist.keygen.sh/v1/{ACCOUNT}/{PRODUCT}/update/{PLATFORM}/{EXTENSION}/{VERSION}

Example requests

# Using bearer authentication
curl -vf -L https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/update/macos/zip/v1.0.0 \
  -H "Authorization: Bearer <%= token %>" \
  -o "v1.3.0.zip"

# Using basic authentication
curl -vf -L https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/update/macos/zip/v1.0.0 \
  -u "bbec-988f-b52f-5188:" \
  -o "v1.3.0.zip"

# Using query parameters
curl -vf -L https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/update/macos/zip/v1.0.0?key=bbec-988f-b52f-5188 \
  -o "v1.3.0.zip"

# or…
curl -vf -GL https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/update/macos/zip/v1.0.0 \
  -d "key=bbec-988f-b52f-5188" \
  -o "v1.3.0.zip"

Example response / 307 Temporary Redirect

Location: https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.3.0.zip?key=bbec-988f-b52f-5188{
  "url": "https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.3.0.zip?key=bbec-988f-b52f-5188",
  "name": "v1.3.0"
}

linkDownload latest

Download the latest release. A valid license key must be specified to download the release. The download request will be rejected for licenses that do not pass validation, and an error will be returned detailing the reason for the validation failure. This endpoint will only look in the top-level root directory / for releases files.

In order to utilize this endpoint, all release keys must follow SemVer for the requested file extension. If any release key does not follow SemVer naming conventions, the update request will fail with a 422 error.

linkAuthentication

  • linkBearer

    To bypass license validation, an authentication token with privileges to manage the resource may be supplied; either an admin or a token that belongs to the product. If a bearer token is not supplied, at a minimum a license key is required to process the request.

  • linkBasic

    Instead of supplying a license key and an optional machine fingerprint as query parameters, you may supply a license key and an optional machine fingerprint as the username and password, respectively, via basic authentication. This is useful for distribution methods that do not accept query parameters, for example, a Rubygems server. Note that when using this method, the license key cannot contain the ':' character.

linkParameters

  • linkaccount

    string, required

    The identifier (UUID) of your Keygen account.

  • linkproduct

    string, required

    The identifier (UUID) of the product the release is for.

  • linkplatform

    string, required

    The platform to scope the download to.

  • linkextension

    string, required

    The file extension to use e.g. zip, dmg, nupkg, tgz, etc.

linkQuery Parameters

  • linkkey

    string, required

    The license key to validate. Please note: this must be the license's key attribute, not its ID.

  • linkchannel

    string, optional, default isstable

    The release channel. One of: stable or prerelease. The prerelease channel will include release candidates, as well as alpha/beta versions.

  • linkfingerprint

    string, optional

    The machine fingerprint to scope the license validation to.

  • linkmachine

    string, optional

    The machine identifier (UUID) to scope the license validation to.

  • linkpolicy

    string, optional

    The policy identifier (UUID) to scope the license validation to.

linkReturns

If a download is available, a 307 Temporary Redirect will be returned pointing to the latest release. Otherwise, 204 No Content will be returned.

When an Accept: application/json header is included in the request, a 200 OK response will be returned instead of a 307 Temporary Redirect.

Definition

https://dist.keygen.sh/v1/{ACCOUNT}/{PRODUCT}/latest/{PLATFORM}/{EXTENSION}

Example requests

# Using bearer authentication
curl -vf -L https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/latest/macos/dmg \
  -H "Authorization: Bearer <%= token %>" \
  -o "v1.3.0.dmg"

# Using basic authentication
curl -vf -L https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/latest/macos/dmg \
  -u "bbec-988f-b52f-5188:" \
  -o "v1.3.0.dmg"

# Using query parameters
curl -vf -L https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/latest/macos/dmg?key=bbec-988f-b52f-5188 \
  -o "v1.3.0.dmg"

# or…
curl -vf -GL https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/latest/macos/dmg \
  -d "key=bbec-988f-b52f-5188" \
  -o "v1.3.0.dmg"

Example response / 307 Temporary Redirect

Location: https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.3.0.dmg?key=bbec-988f-b52f-5188{
  "url": "https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/macos/v1.3.0.dmg?key=bbec-988f-b52f-5188",
  "name": "v1.3.0"
}