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.

linkVersioning

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

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 that includes their new license key:

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

In addition, if you're providing auto-updates, you'll also want to make sure to include a license key or the request will be rejected.

For example, you could do the following for an Electron app:

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

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

const distUrl = `https://dist.keygen.sh/v1/${KEYGEN_ACCOUNT_ID}/${KEYGEN_PRODUCT_ID}`
const feedUrl = `${distUrl}/update/${platform}/zip/${version}?key=${licenseKey}`

autoUpdater.setFeedURL(feedUrl)
autoUpdater.checkForUpdates()

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, 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/.git/objects/00
darwin/.git/objects/01
darwin/v1.0.0.zip
darwin/v1.0.0.dmg
darwin/v1.1.0.zip
darwin/v1.1.0.dmg
darwin/CHANGELOG.md

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/.git/objects/00
/v1/{ACCOUNT}/{PRODUCT}/darwin/.git/objects/01
/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
/v1/{ACCOUNT}/{PRODUCT}/darwin/CHANGELOG.md

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/.git/objects
/v1/{ACCOUNT}/{PRODUCT}/darwin/.git

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.

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

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",
      "key": "1.9.1.zip",
      "platform": "macos"
    }
  }
}

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

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

Definition

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

Example request

curl -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

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

  • linkencrypted

    boolean, optional

    Whether the license implements an encrypted policy. Encrypted licenses will fail validation unless this is specified.

  • 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 https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/releases/linux \
  -H "Authorization: Bearer <%= token %>"

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

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

# or…
curl -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/macos/1.9.1.zip",
        "key": "1.9.1.zip",
        "platform": "macos"
      }
    },
    …
  ]
}

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.

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

  • linkencrypted

    boolean, optional

    Whether the license implements an encrypted policy. Encrypted licenses will fail validation unless this is specified.

  • 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 MD5 integrity checksum.

linkReturns

A 200 OK response will be returned along with the requested release.

Definition

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

Example requests

# Using bearer authentication
curl 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 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 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 -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 the 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.

  • linkencrypted

    boolean, optional

    Whether the license implements an encrypted policy. Encrypted licenses will fail validation unless this is specified.

  • 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 -L https://dist.keygen.sh/v1/<%= account %>/31339351-f7f5-4bdd-8346-5d8399a1ac07/update/macos/zip/v1.0.0 \
  -H "Authorization: Bearer <%= token %>" \
  -o "v1.0.0.zip"

# Using basic authentication
curl -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.0.0.zip"

# Using query parameters
curl -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.0.0.zip"

# or…
curl -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.0.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.zip"
}

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

  • linkencrypted

    boolean, optional

    Whether the license implements an encrypted policy. Encrypted licenses will fail validation unless this is specified.

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

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}/latest/{PLATFORM}/{EXTENSION}

Example requests

# Using bearer authentication
curl -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 -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 -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 -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.dmg"
}