Select programming language for code examples

linkRelease artifacts

An artifact represents an uploaded file for a release. Release artifacts are automatically populated by the current releases. The below endpoints are read-only. To download a release, request the artifact and follow the 303 See Other HTTP redirect.

You may retrieve release artifacts by filename, as an alternative to retrieving by artifact ID. This access pattern may be useful for certain auto-update engines such as electron-builder, which expects to be able to access artifacts by filename, e.g. latest-mac.yml.

To upload or yank a release artifact, please see the given release's artifact relationship. The following artifact endpoints are read-only.

linkThe release artifact object

Below you will find the various attributes for the release artifact resource.

Artifacts can be downloaded according to the following rules:

  • Licenses: can access artifacts for their product, given the artifact was created prior to the license's expiry (if the license has an expiry), and that the license fulfills all of the release's entitlement contraints. This is typically known as a "Perpetual Fallback License."
  • Users: can access artifacts for their products, given the user has one or more associated licenses which fulfill the license requirements above.
  • Products: can access any artifact for their product.
  • Admins: can access any artifact for their account.

linkAttributes

  • linkdata.attributes.key

    stringread only

    The machine-readable key of the artifact. This will match the release's filename.

  • linkdata.attributes.created

    timestamp (ISO8601 format)read only

    When the artifact was uploaded.

  • linkdata.attributes.updated

    timestamp (ISO8601 format)read only

    When the artifact was last updated.

linkRelationships

  • linkdata.relationships.account

    individual

    The account that the artifact belongs to.

Example object

{
"data": {
"id": "ddc77e3f-808d-4344-9926-e885f4a8aa3c",
"type": "artifacts",
"attributes": {
"key": "Product-1-0-0.zip",
"created": "2021-07-26T14:38:43.571Z",
"updated": "2021-07-26T14:40:26.424Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/products/652da162-cd35-4814-bd28-910a0df0dfad"
},
"data": {
"type": "products",
"id": "652da162-cd35-4814-bd28-910a0df0dfad"
}
},
"release": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/releases/30c64dcd-a74d-4f0d-8479-8745172a4817"
},
"data": {
"type": "releases",
"id": "30c64dcd-a74d-4f0d-8479-8745172a4817"
}
}
},
"links": {
"related": "/v1/accounts/{ACCOUNT}/releases/30c64dcd-a74d-4f0d-8479-8745172a4817/artifact",
"self": "/v1/accounts/{ACCOUNT}/artifacts/ddc77e3f-808d-4344-9926-e885f4a8aa3c"
}
}
}

linkDownload a release artifact

Retrieve the release artifact. This can be used to generate temporary download URLs for licensees. Accessing this resource will increment the release's downloads counter by 1. To download the artifact, follow the redirect Location header.

Releases can be downloaded according to the following rules:

  • Licenses: can access releases for their product, given the release was created prior to the license's expiry (if the license has an expiry), and that the license fulfills all of the release's entitlement contraints. Exact behavior will also depend on the product's distribution strategy, and the policy's expiration strategy.
  • Users: can access releases for their products, given the user has one or more associated licenses which fulfill the license requirements above.
  • Products: can access any release for their product.
  • Admins: can access any release for their account.
Use an admin or product token to generate a download link with a time-to-live longer than 60 seconds. E.g. for use inside of a "welcome" email or on a "success" page. Use short-lived download links for "download" buttons inside of a UI portal.

linkAuthentication

  • linkBearer

    optional

    An authentication token with privileges to read the release artifact: either an admin, the product it belongs to, an entitled license (via an activation token), or a user with an entitled license. If the product's distribution strategy is OPEN, no authentication is required.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

  • link:artifact

    string, required

    The identifier (UUID) or the key (filename) of the artifact to be retrieved. If you have multiple products, we recommend adding a product-specific prefix to all release filenames in order to avoid conflicts when accessing artifacts by key.

linkQuery Parameters

  • linkttl

    integer, optional, default is60protectedProtected params are only available for bearers with an admin or product role.

    The time-to-live (TTL), in seconds, for the download link. The value can be between 1 minute and 1 week, in seconds. Only admins and products can set this parameter.

linkReturns

A 303 See Other status will be returned redirecting to the download URL for the artifact, hosted on AWS S3. Follow the redirect to download the release.

Please note: If you receive a 400 error from AWS S3, you may need to configure your HTTP client to not automatically follow redirects. Some HTTP clients will insecurely replay the entire request, including your Keygen Authorization header, to the cross-origin AWS S3 resource, resulting in a 400 response from S3. You can manually follow the redirect by issuing a GET request to the Location header, without the superfluous headers.

Alternatively, you can pass in your API token via the request's query parameters, e.g. ?token=activ-XXX, instead of the Authorization header.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts/{ARTIFACT}

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts/keygen-ent/on-prem-1-0-0.tar.gz", {
redirect: "manual",
method: "GET",
headers: {
"Authorization": "Bearer {TOKEN}",
"Accept": "application/vnd.api+json"
}
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.get(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts/keygen-ent/on-prem-1-0-0.tar.gz",
headers={
"Authorization": "Bearer {TOKEN}",
"Accept": "application/vnd.api+json"
}
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts/keygen-ent/on-prem-1-0-0.tar.gz",
headers: [
"Authorization": "Bearer {TOKEN}",
"Accept": "application/vnd.api+json"
]
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest(
"artifacts/keygen-ent/on-prem-1-0-0.tar.gz",
Method.GET
);
 
request.AddHeader("Authorization", "Bearer {TOKEN}");
request.AddHeader("Accept", "application/vnd.api+json");
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.get("https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts/keygen-ent/on-prem-1-0-0.tar.gz")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.get("https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts/keygen-ent/on-prem-1-0-0.tar.gz")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/artifacts/keygen-ent/on-prem-1-0-0.tar.gz");
req.set_method(methods::GET);
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts/keygen-ent/on-prem-1-0-0.tar.gz \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Accept: application/vnd.api+json'

Example response / 303 See Other

Location: https://keygen-dist.s3.us-east-2.amazonaws.com/artifacts/{ACCOUNT}/30c64dcd-a74d-4f0d-8479-8745172a4817/keygen-ent/on-prem-1-0-0.tar.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIMMTBUOYHFTLV23Q%2F20210720%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20210720T145510Z&X-Amz-Expires=60&X-Amz-SignedHeaders=host&X-Amz-Signature=8b9d214c0db8116a0c96d93140dda5367183e36ee367d00c82267a40546d3927
{
"data": {
"id": "ddc77e3f-808d-4344-9926-e885f4a8aa3c",
"type": "artifacts",
"attributes": {
"key": "keygen-ent/on-prem-1-0-0.tar.gz",
"created": "2021-07-26T14:38:43.571Z",
"updated": "2021-07-26T14:40:26.424Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/products/652da162-cd35-4814-bd28-910a0df0dfad"
},
"data": {
"type": "products",
"id": "652da162-cd35-4814-bd28-910a0df0dfad"
}
},
"release": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/releases/30c64dcd-a74d-4f0d-8479-8745172a4817"
},
"data": {
"type": "releases",
"id": "30c64dcd-a74d-4f0d-8479-8745172a4817"
}
}
},
"links": {
"related": "/v1/accounts/{ACCOUNT}/releases/30c64dcd-a74d-4f0d-8479-8745172a4817/artifact",
"self": "/v1/accounts/{ACCOUNT}/artifacts/ddc77e3f-808d-4344-9926-e885f4a8aa3c"
}
}
}

linkList all release artifacts

Returns a list of release artifacts. The artifacts are returned sorted by upload date, with the most recent artifacts appearing first.

linkAuthentication

  • linkBearer

    optional

    An authentication token with privileges to read the artifacts: either an admin, the product the releases belong to, an entitled license (via an activation token), or a user with an entitled license. If the product's distribution strategy is OPEN, no authentication is required.

linkURL Parameters

  • link:account

    string, required

    The identifier (UUID) or slug of your Keygen account.

linkFilters

  • linklimit

    integer, default is10

    A limit on the number of artifacts to be returned. Limit must be a number between 1 and 100.

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts?limit=25
  • linkpage

    object<string, integer>

    Object containing page size and page number. Page size must be a number between 1 and 100

    https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts?page[size]=15&page[number]=2

linkReturns

A 200 OK response will be returned along with a list of artifact objects.

Upon error, an errors object will be returned along with an HTTP status code indicating the type of error. When an error occurs, the data property will not be included.

Definition

https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts{FILTERS}

Example request

const fetch = require("node-fetch")
 
const response = await fetch("https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts?limit=15", {
method: "GET",
headers: {
"Authorization": "Bearer {TOKEN}",
"Accept": "application/vnd.api+json"
}
})
 
const { data, errors } = await response.json()
import requests
import json
 
res = requests.get(
"https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts?limit=15",
headers={
"Authorization": "Bearer {TOKEN}",
"Accept": "application/vnd.api+json"
}
).json()
import SwiftyJSON
import Alamofire
 
Alamofire.request("https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts?limit=15",
headers: [
"Authorization": "Bearer {TOKEN}",
"Accept": "application/vnd.api+json"
]
).responseJSON { response in
let json = JSON(data: response.data!)
}
using RestSharp;
 
var client = new RestClient("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
var request = new RestRequest("artifacts", Method.GET);
 
request.AddHeader("Authorization", "Bearer {TOKEN}");
request.AddHeader("Accept", "application/vnd.api+json");
 
request.AddParameter("limit", 15);
 
var response = client.Execute(request);
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*
 
val res = Unirest.get("https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.queryString("limit", 15)
.asJson()
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;
 
HttpResponse<JsonNode> res = Unirest.get("https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts")
.header("Authorization", "Bearer {TOKEN}")
.header("Accept", "application/vnd.api+json")
.queryString("limit", 15)
.asJson();
#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/filestream.h>
 
using namespace std;
using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/{ACCOUNT}");
http_request req;
 
req.headers().add("Authorization", "Bearer {TOKEN}");
req.headers().add("Accept", "application/json");
 
uri_builder uri("/artifacts");
uri.append_query("limit", 15);
 
req.set_request_uri(uri.to_uri());
req.set_method(methods::GET);
 
client.request(req)
.then([](http_response res) {
auto data = res.extract_json().get();
})
.wait();
curl https://api.keygen.sh/v1/accounts/{ACCOUNT}/artifacts?limit=15 -g \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Accept: application/vnd.api+json'

Example response / 200 OK

{
"data": [
{
"id": "ddc77e3f-808d-4344-9926-e885f4a8aa3c",
"type": "artifacts",
"attributes": {
"key": "Product-1-0-0.zip",
"created": "2021-07-26T14:38:43.571Z",
"updated": "2021-07-26T14:40:26.424Z"
},
"relationships": {
"account": {
"links": {
"related": "/v1/accounts/{ACCOUNT}"
},
"data": {
"type": "accounts",
"id": "{ACCOUNT}"
}
},
"product": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/products/652da162-cd35-4814-bd28-910a0df0dfad"
},
"data": {
"type": "products",
"id": "652da162-cd35-4814-bd28-910a0df0dfad"
}
},
"release": {
"links": {
"related": "/v1/accounts/{ACCOUNT}/releases/30c64dcd-a74d-4f0d-8479-8745172a4817"
},
"data": {
"type": "releases",
"id": "30c64dcd-a74d-4f0d-8479-8745172a4817"
}
}
},
"links": {
"related": "/v1/accounts/{ACCOUNT}/releases/30c64dcd-a74d-4f0d-8479-8745172a4817/artifact",
"self": "/v1/accounts/{ACCOUNT}/artifacts/ddc77e3f-808d-4344-9926-e885f4a8aa3c"
}
}
]
}