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

linkDistribution

linkDownload Links

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.

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.

The download URL will remain accessible for as long as the license is valid.

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 should create a separate license policy that doesn't require a fingerprint scope, used solely for the initial download. You can also give it a short duration e.g. 1 day. This would result in your customer receiving 2 license keys—a temporary "download key", and a "normal" license key.

Example Download 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.

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

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"
      }
    },
    …
  ]
}

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 to scope releases 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.

  • 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 to scope releases to.

  • linkrelease

    string, required

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

linkQuery Parameters

  • linkkey

    string, required

    The license key to validate.

  • 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 releases 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.

  • 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 releases 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.

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