Keygen

https://keygen.sh/docs
Admin
Keygen is a fair source software licensing and distribution API.
Tokens:708,770
Snippets:3,931
Trust Score:9.5
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### GET /v1/accounts/<account>/artifacts/install.sh

Source: https://keygen.sh/docs/api/artifacts

Example request to retrieve the install script artifact for a specific account.

```APIDOC
## [GET] /v1/accounts/<account>/artifacts/install.sh

### Description
Retrieves the install script artifact for a specific account. This endpoint is used to fetch the installation script for the Keygen API.

### Method
GET

### Endpoint
https://api.keygen.sh/v1/accounts/<account>/artifacts/install.sh

### Parameters
#### Path Parameters
- **account** (string) - Required - The account identifier.

### Request Example
```
curl https://api.keygen.sh/v1/accounts/<account>/artifacts/install.sh \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/vnd.api+json'
```

### Response
#### Success Response (200)
- **body** (JsonNode) - The response body containing the artifact data.

#### Response Example
```
{
  "data": {}
}
```
```

--------------------------------

### GET raw.pkg.keygen.sh/<account>/relay/latest/install.sh

Source: https://keygen.sh/docs/api/engines

Example request and response for fetching the latest relay install script.

```APIDOC
## [GET] https://raw.pkg.keygen.sh/<account>/relay/latest/install.sh

### Description
Fetches the latest install script for the relay package. The request should be made with a redirect policy of manual to capture the redirect response.

### Method
GET

### Endpoint
https://raw.pkg.keygen.sh/<account>/relay/latest/install.sh

### Parameters
#### Path Parameters
- **account** (string) - Required - The account identifier.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```
curl https://raw.pkg.keygen.sh/<account>/relay/latest/install.sh \
  -H 'Authorization: Bearer <token>'
```

### Response
#### Success Response (303 See Other)
- **Location** (string) - The redirect URL to the actual install script artifact.

#### Response Example
```
Location: https://api.keygen.sh/v1/accounts/<account>/artifacts/30c64dcd-a74d-4f0d-8479-8745172a4817/install.sh
```
```

--------------------------------

### List platforms example request in Kotlin

Source: https://keygen.sh/docs/api/platforms

Example GET request using Unirest. Adds limit as a query string parameter.

```kotlin
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*

val res = Unirest.get("https://api.keygen.sh/v1/accounts/<account>/platforms")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .queryString("limit", 15)
  .asJson()
```

--------------------------------

### Example response / 303 See Other

Source: https://keygen.sh/docs/api/engines

Example response header showing a 303 See Other redirect. The Location header points to the actual install script artifact URL.

```http
Location: https://api.keygen.sh/v1/accounts/<account>/artifacts/30c64dcd-a74d-4f0d-8479-8745172a4817/install.sh
```

--------------------------------

### Install with --index-url

Source: https://keygen.sh/docs/api/engines

Instructions for installing packages using the PyPI engine with the --index-url flag, including examples with and without license authentication.

```APIDOC
## Install with --index-url

### Description
Install a package that implements the `pypi` engine using `pip`. Only packages that implement the `pypi` engine will be available for install. Packages for other engines, or packages without an engine, will not be available. In addition, only packages which are available to the current requestor will be included, e.g. if you don't authenticate then only `OPEN` packages will be included.

### Usage
Prefer `--index-url` over `--extra-index-url` for security reasons. Because `pip` does not lock dependencies to specific repositories, and because `pip` provides no protection from package spoofing, we recommend using Keygen as the sole package index. All non-Keygen packages will be securely redirected to PyPI for fulfillment (also known as a "pass through" PyPI repository). This prevents `pip` from installing a package with the same name from PyPI instead of Keygen, preventing a supply chain attack vector. Alternatively, you can add the `--index-url` flag to your `requirements.txt`.

### Example with license authentication
```bash
pip install <package> \
  --index-url https://license:<key>@pypi.pkg.keygen.sh/<account>/simple
```

### Example without authentication
```bash
pip install <package> \
  --index-url https://pypi.pkg.keygen.sh/<account>/simple
```
```

--------------------------------

### List platforms example request in C#

Source: https://keygen.sh/docs/api/platforms

Example GET request using RestSharp. Adds limit as a parameter.

```csharp
using RestSharp;

var client = new RestClient("https://api.keygen.sh/v1/accounts/<account>");
var request = new RestRequest("platforms", Method.GET);

request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Accept", "application/vnd.api+json");

request.AddParameter("limit", 15);

var response = client.Execute(request);
```

--------------------------------

### Example package.json for scoped install

Source: https://keygen.sh/docs/api/engines

Example package.json that instructs npm to install a scoped package from the private registry. Replace @your-scope/<package> with your actual scope and package name.

```json
{
  "private": true,
  "dependencies": {
    "@your-scope/<package>": "1.0.0"
  }
}
```

--------------------------------

### C++ cpprest GET install.sh artifact

Source: https://keygen.sh/docs/api/artifacts

C++ example using cpprest to fetch the install.sh artifact. It sets the Authorization and Accept headers, performs a GET request, and extracts the JSON response. Replace <account> and <token> with your credentials.

```cpp
#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/install.sh");
req.set_method(methods::GET);
 
client.request(req)
  .then([](http_response res) {
    auto data = res.extract_json().get();
  })
  .wait();
```

--------------------------------

### List platforms example request in Swift

Source: https://keygen.sh/docs/api/platforms

Example GET request using Alamofire and SwiftyJSON. Handles the response as JSON.

```swift
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<account>/platforms?limit=15",
  headers: [
    "Authorization": "Bearer <token>",
    "Accept": "application/vnd.api+json"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
```

--------------------------------

### Example request in C++ (cpprest)

Source: https://keygen.sh/docs/api/sandbox

Sends a GET request to the licenses endpoint with the sandbox environment header.

```cpp
#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("Keygen-Environment", "sandbox");
req.headers().add("Authorization", "Bearer <token>");
req.headers().add("Accept", "application/json");

uri_builder uri("/licenses");

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();
```

--------------------------------

### Example request in Swift

Source: https://keygen.sh/docs/api/sandbox

Sends a GET request to the licenses endpoint with the sandbox environment header.

```swift
import SwiftyJSON
import Alamofire

Alamofire.request("https://api.keygen.sh/v1/accounts/<account>/licenses",
  headers: [
    "Keygen-Environment": "sandbox",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  ]
).responseJSON { response in
  let json = JSON(data: response.data!)
}
```

--------------------------------

### Example request in Kotlin (Unirest)

Source: https://keygen.sh/docs/api/sandbox

Sends a GET request to the licenses endpoint with the sandbox environment header.

```kotlin
import com.mashape.unirest.http.exceptions.*
import com.mashape.unirest.http.*

val res = Unirest.get("https://api.keygen.sh/v1/accounts/<account>/licenses")
  .header("Keygen-Environment", "sandbox")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .asJson()
```

--------------------------------

### Example request in Java (Unirest)

Source: https://keygen.sh/docs/api/sandbox

Sends a GET request to the licenses endpoint with the sandbox environment header.

```java
import com.mashape.unirest.http.exceptions.*;
import com.mashape.unirest.http.*;

HttpResponse<JsonNode> res = Unirest.get("https://api.keygen.sh/v1/accounts/<account>/licenses")
  .header("Keygen-Environment", "sandbox")
  .header("Authorization", "Bearer <token>")
  .header("Accept", "application/vnd.api+json")
  .asJson();
```

--------------------------------

### Example request in Python

Source: https://keygen.sh/docs/api/sandbox

Sends a GET request to the licenses endpoint with the sandbox environment header.

```python
import requests
import json

res = requests.get(
  "https://api.keygen.sh/v1/accounts/<account>/licenses",
  headers={
    "Keygen-Environment": "sandbox",
    "Accept": "application/vnd.api+json",
    "Authorization": "Bearer <token>"
  }
).json()
```

--------------------------------

### Create a machine (C++ example)

Source: https://keygen.sh/docs/api/machines

C++ example using the Keygen client library to create a machine. It sets the Authorization, Content-Type, and Accept headers, sets the request URI to /machines, uses POST method, serializes the body, and sends the request.

```cpp
req.headers().add("Authorization", "Bearer <token>");
req.headers().add("Content-Type", "application/vnd.api+json");
req.headers().add("Accept", "application/json");

req.set_request_uri("/machines");
req.set_method(methods::POST);
req.set_body(body.serialize());

client.request(req)
  .then([](http_response res)
  {
    auto data = res.extract_json().get();
  })
  .wait();
```

--------------------------------

### Create product with cpprest (C++)

Source: https://keygen.sh/docs/api/products

C++ example using cpprest to create a product. Builds a JSON body with name, URL, and platforms, then sends a POST request to the /products endpoint. Requires a valid bearer token.

```cpp
#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 web::json;
using namespace utility;
 
http_client client("https://api.keygen.sh/v1/accounts/<account>");
http_request req;
 
value platforms;
platforms[0] = value::string("iOS");
platforms[1] = value::string("Android");
 
value attrs;
attrs["name"] = value::string("Example On-Premise");
attrs["url"] = value::string("https://example.com");
attrs["platforms"] = platforms;
 
value data;
data["type"] = value::string("products");
data["attributes"] = attrs;
 
value body;
body["data"] = data;
 
req.headers().add("Authorization", "Bearer <token>");
req.headers().add("Content-Type", "application/vnd.api+json");
req.headers().add("Accept", "application/json");
 
req.set_request_uri("/products");
req.set_method(methods::POST);
req.set_body(body.serialize());
 
client.request(req)
  .then([](http_response res)
  {
    auto data = res.extract_json().get();
  })
  .wait();
```

--------------------------------

### Go: Check and install upgrade with keygen-go

Source: https://keygen.sh/docs/api/auto-updates

Configures the Keygen Go SDK with account, product, and license key, then checks for an upgrade using keygen.Upgrade. If an upgrade is available, it installs it and prints the new version. Handles the ErrUpgradeNotAvailable case and panics on install failure.

```go
import "github.com/keygen-sh/keygen-go"

func upgrade() error {
  keygen.Account = "1fddcec8-8dd3-4d8d-9b16-215cac0f9b52"
  keygen.Product = "1f086ec9-a943-46ea-9da4-e62c2180c2f4"
  keygen.LicenseKey = "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3"

  opts := keygen.UpgradeOptions{CurrentVersion: "1.0.0", Channel: "stable", PublicKey: "5ec69b78d4b5d4b624699cef5faf3347dc4b06bb807ed4a2c6740129f1db7159"}

  // Check for an upgrade
  release, err := keygen.Upgrade(opts)
  switch {
  case err == keygen.ErrUpgradeNotAvailable:
    fmt.Println("No upgrade available, already at the latest version!")

    return nil
  case err != nil:
    fmt.Println("Upgrade check failed!")

    return err
  }

  // Install the upgrade
  if err := release.Install(); err != nil {
    panic("Upgrade install failed!")
  }

  fmt.Printf("Upgrade complete! Installed v%s. Please restart.\n", release.Version)
}
```

--------------------------------

### List platforms example request in Python

Source: https://keygen.sh/docs/api/platforms

Example GET request using requests library. Parses the JSON response.

```python
import requests
import json

res = requests.get(
  "https://api.keygen.sh/v1/accounts/<account>/platforms?limit=15",
  headers={
    "Authorization": "Bearer <token>",
    "Accept": "application/vnd.api+json"
  }
).json()
```

--------------------------------

### Install gem with --source and license authentication (generic)

Source: https://keygen.sh/docs/api/engines

Installs a gem using the `--source` flag with license authentication. Replace `<gem>`, `<key>`, and `<account>` with your values.

```bash
gem install '<gem>' \
  --source https://license:<key>@rubygems.pkg.keygen.sh/<account>
gem install '<gem>' \
  --source https://license:<key>@rubygems.pkg.keygen.sh/<account>
```

--------------------------------

### Verify keygen installation with --help

Source: https://keygen.sh/docs/cli

Confirms the installation by displaying the CLI help output.

```bash
keygen --help
```

--------------------------------

### Get macOS machine GUID with ioreg

Source: https://keygen.sh/docs/activating-machines

Retrieves the native machine GUID (IOPlatformUUID) on macOS, which can be used as a device fingerprint for machine activation.

```shell
ioreg -rd1 -c IOPlatformExpertDevice

```

--------------------------------

### C++ GET request to Keygen API

Source: https://keygen.sh/docs/api/releases

C++ example using cpprestsdk to make a GET request to the Keygen API and extract JSON from the response.

```cpp
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();
```

--------------------------------

### GET /v1/accounts/<account>/releases

Source: https://keygen.sh/docs/api/releases

Example request to list releases for an account, demonstrating the GET endpoint with query parameter `limit` and required headers.

```APIDOC
## GET /v1/accounts/<account>/releases

### Description
List releases for an account, with optional pagination via the `limit` query parameter.

### Method
GET

### Endpoint
https://api.keygen.sh/v1/accounts/<account>/releases

### Parameters
#### Path Parameters
- **account** (string) - Required - The account identifier.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of releases to return.

### Request Example
```
curl https://api.keygen.sh/v1/accounts/<account>/releases?limit=15 -g \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **data** (array) - List of release objects.

#### Response Example
```
{
  "data": []
}
```
```

--------------------------------

### List platforms example request in JavaScript

Source: https://keygen.sh/docs/api/platforms

Example GET request using node-fetch. Requires a bearer token and Accept header for JSON API.

```javascript
const fetch = require("node-fetch")

const response = await fetch("https://api.keygen.sh/v1/accounts/<account>/platforms?limit=15", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <token>",
    "Accept": "application/vnd.api+json"
  }
})

const { data, errors } = await response.json()
```

--------------------------------

### Install a package from the Keygen PyPI repository

Source: https://keygen.sh/docs/api/engines

Installs a package from the Keygen private PyPI repository using the license key as the password. Replace <key> and <account> with your actual values.

```bash
pip install --index-url https://license:<key>@pypi.pkg.keygen.sh/<account>/simple machineid
```

--------------------------------

### GET /v1/accounts/<account>/request-logs

Source: https://keygen.sh/docs/api/request-logs

This snippet documents the GET endpoint for listing request logs for an account. It includes the endpoint path, query parameters, and a detailed example response.

```APIDOC
## [GET] /v1/accounts/<account>/request-logs

### Description
Retrieves a list of request logs for the specified account. The response includes detailed attributes such as URL, method, status, headers, body, and related resources.

### Method
GET

### Endpoint
/v1/accounts/<account>/request-logs

### Parameters
#### Path Parameters
- **account** (string) - Required - The account identifier.

#### Query Parameters
- **limit** (integer) - Optional - Limits the number of request logs returned. Example: `limit=15`.

### Request Example
```
curl https://api.keygen.sh/v1/accounts/<account>/request-logs?limit=15 -g \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/vnd.api+json'
```

### Response
#### Success Response (200)
- **data** (array) - List of request log objects.
  - **id** (string) - Unique identifier for the request log.
  - **type** (string) - Always `request-logs`.
  - **attributes** (object) - Contains request log details.
    - **url** (string) - The request URL path.
    - **method** (string) - HTTP method used.
    - **status** (string) - HTTP status code.
    - **userAgent** (string) - User agent of the client.
    - **ip** (string) - IP address of the client.
    - **requestHeaders** (object) - Request headers.
    - **requestBody** (string) - Request body as a JSON string.
    - **responseSignature** (string) - Response signature.
    - **responseHeaders** (object) - Response headers.
    - **responseBody** (string) - Response body as a JSON string.
    - **created** (string) - Creation timestamp.
    - **updated** (string) - Last update timestamp.
  - **relationships** (object) - Related resources.
    - **account** (object) - Related account.
    - **environment** (object) - Related environment (may be null).
    - **requestor** (object) - Related requestor (e.g., license).
  - **links** (object) - Self link.

#### Response Example
```
{
  "data": [
    {
      "id": "51bf85b8-85f1-4665-977d-69adb46915b5",
      "type": "request-logs",
      "attributes": {
        "url": "/v1/accounts/<account>/machines",
        "method": "POST",
        "status": "422",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
        "ip": "192.168.1.1",
        "requestHeaders": {
          "Host": "api.keygen.sh",
          "Accept": "application/json",
          "Content-Type": "application/json",
          "Content-Length": "298"
        },
        "requestBody": "{\"data\":{\"type\":\"machine\",\"attributes\":{\"fingerprint\":\"6a8e6304-9184-465a-9273-b7f9d4981f12\",\"name\":\"Demo Device 3e73f\",\"platform\":\"Windows 10\",\"metadata\":{\"browser\":\"chrome\",\"version\":\"125.0.0\"}},\"relationships\":{\"license\":{\"data\":{\"type\":\"license\",\"id\":\"1a8845c8-ff5d-4dab-a805-5b58efe0c9d2\"}}}}}",
        "responseSignature": "keyid=\"<account>\", algorithm=\"ed25519\", signature=\"sgCO/65/JxiNdM68gNp/uUkNYf9UDpP262YSbzprXMNKoqHcgmqgzsOn+KsYrvGXgVMuxMKqEQu7FpNCK86QDQ==\", headers=\"(request-target) host date digest\"",
        "responseHeaders": {
          "Date": "Tue, 04 Jun 2024 16:18:36 GMT",
          "Digest": "sha-256=jexOw5i/zQJbcv8WOVcHkOQ2lnRc1dJH+GoVNaR8G4U=",
          "Keygen-Date": "Tue, 04 Jun 2024 16:18:36 GMT",
          "Keygen-Mode": "multiplayer",
          "Content-Type": "application/json; charset=utf-8",
          "Keygen-Digest": "sha-256=jexOw5i/zQJbcv8WOVcHkOQ2lnRc1dJH+GoVNaR8G4U=",
          "Keygen-Edition": "EE",
          "Keygen-License": "id=\"645993cd-e5f4-40e4-8a43-b35cefd04a8d\", iss=\"2023-03-15 20:03:03 UTC\", exp=\"\"",
          "Keygen-Version": "1.2",
          "Keygen-Signature": "keyid=\"<account>\", algorithm=\"ed25519\", signature=\"sgCO/65/JxiNdM68gNp/uUkNYf9UDpP262YSbzprXMNKoqHcgmqgzsOn+KsYrvGXgVMuxMKqEQu7FpNCK86QDQ==\", headers=\"(request-target) host date digest\""
        },
        "responseBody": "{\"errors\":[{\"title\":\"Unprocessable resource\",\"detail\":\"machine count has exceeded maximum allowed for license (10)\",\"code\":\"MACHINE_LIMIT_EXCEEDED\",\"source\":{\"pointer\":\"/data\"},\"links\":{\"about\":\"https://keygen.sh/docs/api/machines/#machines-object\"}}],\"meta\":{\"id\":\"51bf85b8-85f1-4665-977d-69adb46915b5\"}}",
        "created": "2024-06-04T16:18:36.789Z",
        "updated": "2024-06-04T16:18:36.829Z"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<account>"
          },
          "data": {
            "type": "accounts",
            "id": "<account>"
          }
        },
        "environment": {
          "links": {
            "related": null
          },
          "data": null
        },
        "requestor": {
          "links": {
            "related": "/v1/accounts/<account>/licenses/1a8845c8-ff5d-4dab-a805-5b58efe0c9d2"
          },
          "data": {
            "type": "licenses",
            "id": "1a8845c8-ff5d-4dab-a805-5b58efe0c9d2"
          }
        }
      },
      "links": {
        "self": "/v1/accounts/<account>/request-logs/51bf85b8-85f1-4665-977d-69adb46915b5"
      }
    }
  ]
}
```
```

--------------------------------

### Verify relay installation with --help

Source: https://keygen.sh/docs/relay

Confirms the installation by displaying relay's help output.

```bash
relay --help
relay --help
_content_copy_
```

--------------------------------

### GET /v1/accounts/<account>/users

Source: https://keygen.sh/docs/api/pagination

Example request for listing users with pagination parameters.

```APIDOC
## GET /v1/accounts/<account>/users

### Description
Fetches a paginated list of users for a given account, using cursor-based pagination with page[size] and page[cursor] query parameters.

### Method
GET

### Endpoint
https://api.keygen.sh/v1/accounts/<account>/users

### Parameters
#### Query Parameters
- **page[size]** (integer) - Optional - The number of records to return per page.
- **page[cursor]** (string) - Optional - The cursor indicating the position from which to start fetching records.

### Request Example
```
curl 'https://api.keygen.sh/v1/accounts/<account>/users?page[size]=25&page[cursor]=4a3eb389-5742-49f2-92f8-29347196a265' -g \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **data** (array) - List of user objects.
- **meta** (object) - Pagination metadata, including cursor information.

#### Response Example
```
{
  "data": [
    {
      "id": "4a3eb389-5742-49f2-92f8-29347196a265",
      "type": "users",
      "attributes": {}
    }
  ],
  "meta": {
    "pagination": {
      "cursor": "..."
    }
  }
}
```
```

--------------------------------

### GET /v1/accounts/<account>/users

Source: https://keygen.sh/docs/api/pagination

Example request for listing users with cursor-based pagination.

```APIDOC
## GET /v1/accounts/<account>/users

### Description
List users with cursor-based pagination. This endpoint supports the `page[size]` and `page[cursor]` query parameters to paginate through the result set.

### Method
GET

### Endpoint
/v1/accounts/<account>/users

### Parameters
#### Query Parameters
- **page[size]** (integer) - Optional - The page size. Must be a number between 1 and 100. Default is 10.
- **page[cursor]** (string) - Optional - The page cursor. Must be the UUID of a resource, representing the starting point of the page (exclusive), or an empty string.
- **page[number]** (integer) - Optional - The page number. Must be a number between 1 and 100. Deprecated.

### Request Example
```
GET /v1/accounts/<account>/users?page[size]=25&page[cursor]=4a3eb389-5742-49f2-92f8-29347196a265
```

### Response
#### Success Response (200)
- **data** (array) - The list of resources.
- **links** (object) - Contains a `next` URI for the next page, or `null` if at the end.
- **errors** (array) - Any errors encountered.

#### Response Example
```json
{
  "data": [],
  "links": {
    "next": null
  }
}
```
```

--------------------------------

### Run Keygen setup container with Docker Compose

Source: https://keygen.sh/docs/self-hosting

Run the setup container to initialize the Keygen environment. The output should be noted for later configuration.

```bash
docker compose --profile setup run --rm setup
```

--------------------------------

### List products with cpprestsdk (C++)

Source: https://keygen.sh/docs/api/products

C++ example using cpprestsdk to list products from the Keygen API. Requires an account ID and a valid bearer token. The response is extracted as JSON.

```cpp
#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("/products");
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();
```

--------------------------------

### GET /v1/accounts/<account>/licenses/{licenseId}/users

Source: https://keygen.sh/docs/api/licenses

This snippet documents the GET endpoint for listing users associated with a license, including the request parameters and example requests in multiple languages.

```APIDOC
## [GET] /v1/accounts/<account>/licenses/{licenseId}/users

### Description
Lists all users associated with a specific license. This endpoint requires authentication and returns a JSON:API response.

### Method
GET

### Endpoint
https://api.keygen.sh/v1/accounts/<account>/licenses/{licenseId}/users

### Parameters
#### Path Parameters
- **account** (string) - Required - The account identifier.
- **licenseId** (string) - Required - The license identifier (e.g., b18e3f3a-330c-4d8d-ae2e-014db21fa827).

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of users to return (e.g., 15).

### Request Example
```
curl https://api.keygen.sh/v1/accounts/<account>/licenses/b18e3f3a-330c-4d8d-ae2e-014db21fa827/users?limit=15 -g \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **data** (array) - List of user resources.

#### Response Example
```json
{
  "data": []
}
```
```

--------------------------------

### GET /v1/accounts/<account>/policies/<policy_id>/entitlements

Source: https://keygen.sh/docs/api/policies

This snippet documents the GET endpoint for listing entitlements of a policy. It includes the endpoint path, parameters, request example, and response structure.

```APIDOC
## GET /v1/accounts/<account>/policies/<policy_id>/entitlements

### Description
Retrieves a list of entitlements for a specific policy. This endpoint returns a collection of entitlement objects associated with the given policy.

### Method
GET

### Endpoint
`/v1/accounts/<account>/policies/<policy_id>/entitlements`

### Parameters
#### Path Parameters
- **account** (string) - Required - The account identifier.
- **policy_id** (string) - Required - The policy identifier. In the example, the policy ID is `0b4b1a9a-e25a-4f14-a95e-d9dd378d6065`.

#### Query Parameters
- **limit** (integer) - Optional - Limits the number of entitlements returned. In the example, `limit=15`.

### Request Example
```
curl https://api.keygen.sh/v1/accounts/<account>/policies/0b4b1a9a-e25a-4f14-a95e-d9dd378d6065/entitlements?limit=15 -g \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200 OK)
Returns a JSON object with a `data` array containing entitlement objects. Each entitlement has the following fields:
- **id** (string) - The entitlement ID.
- **type** (string) - Always `"entitlements"`.
- **attributes** (object) - Contains `name`, `code`, `metadata`, `created`, and `updated` fields.
- **relationships** (object) - Contains an `account` relationship with links and data.
- **links** (object) - Contains a `self` link to the entitlement.

#### Response Example
```
{
  "data": [
    {
      "id": "db1ff21b-f42f-4623-952b-ca7f2600bded",
      "type": "entitlements",
      "attributes": {
        "name": "Example Feature",
        "code": "EXAMPLE_FEATURE",
        "metadata": {},
        "created": "2017-01-02T20:26:53.464Z",
        "updated": "2017-01-02T20:26:53.464Z"
      },
      "relationships": {
        "account": {
          "links": {
            "related": "/v1/accounts/<account>"
          },
          "data": {
            "type": "accounts",
            "id": "<account>"
          }
        }
      },
      "links": {
        "self": "/v1/accounts/<account>/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded"
      }
    }
  ]
}
```
```

--------------------------------

### Start Keygen with Docker Compose

Source: https://keygen.sh/docs/self-hosting

After configuring the .env file, start the Keygen stack with Docker Compose.

```bash
docker compose up
```

--------------------------------

### GET /v1/accounts/<account>/releases/2.0.0/artifacts

Source: https://keygen.sh/docs/api/releases

Example requests in multiple languages for retrieving release artifacts.

```APIDOC
## GET /v1/accounts/<account>/releases/2.0.0/artifacts

### Description
Retrieves the artifacts associated with a specific release version. This endpoint requires authentication and returns a JSON:API response.

### Method
GET

### Endpoint
https://api.keygen.sh/v1/accounts/<account>/releases/2.0.0/artifacts

### Parameters
#### Path Parameters
- **account** (string) - Required - The account identifier.

#### Query Parameters
- **limit** (integer) - Optional - Limits the number of artifacts returned. (Shown in some examples)

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Accept** (string) - Required - Must be `application/vnd.api+json`.

### Request Example
```
GET /v1/accounts/<account>/releases/2.0.0/artifacts HTTP/1.1
Host: api.keygen.sh
Authorization: Bearer <token>
Accept: application/vnd.api+json
```

### Response
#### Success Response (200)
- **data** (object) - The artifact data.
- **errors** (array) - Any errors encountered.

#### Response Example
```json
{
  "data": {},
  "errors": []
}
```
```

--------------------------------

### GET /v1/accounts/<account>/releases/{id}

Source: https://keygen.sh/docs/api/releases

Example request to retrieve a specific release by its ID.

```APIDOC
## [GET] /v1/accounts/<account>/releases/{id}

### Description
Retrieves a specific release by its ID.

### Method
GET

### Endpoint
https://api.keygen.sh/v1/accounts/<account>/releases/{id}

### Parameters
#### Path Parameters
- **account** (string) - Required - The account identifier.
- **id** (string) - Required - The release ID.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Accept** (string) - Required - Must be `application/vnd.api+json`.

### Request Example
```
curl https://api.keygen.sh/v1/accounts/<account>/releases/30c64dcd-a74d-4f0d-8479-8745172a4817 \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/vnd.api+json'
```

### Response
#### Success Response (200)
Returns the release object in JSON:API format.

#### Response Example
```json
{
  "data": {
    "id": "30c64dcd-a74d-4f0d-8479-8745172a4817",
    "type": "releases",
    "attributes": {}
  }
}
```
```

--------------------------------

### Example .pypirc configuration for Keygen

Source: https://keygen.sh/docs/api/engines

Example .pypirc configuration that adds a keygen index server for the Keygen PyPI repository while keeping the public PyPI and test PyPI servers. Replace <account> and <key> with your values.

```ini
[distutils]
index-servers =
  keygen # NB: see note above

[keygen]
repository = https://pypi.pkg.keygen.sh/<account>/simple
username = license
password = <key>

[pypi]
repository = https://upload.pypi.org/legacy/

[testpypi]
repository = https://test.pypi.org/legacy/
```

--------------------------------

### Example response for product token creation

Source: https://keygen.sh/docs/api/products

Example response for a successful product token creation. Shows the token object with its attributes and relationships.

```json
{
  "data": {
    "id": "07d52aa8-b96c-4b55-b05d-f5f570e1775a",
    "type": "tokens",
    "attributes": {
      "kind": "product-token",
      "token": "prod-2ddd064509b6bcaa356958dcce6da3a538919e13ddbc26b359fb374ff89dfacav3",
      "expiry": "2022-03-15T19:27:50.440Z",
      "permissions": ["license.create", "machine.create", ...],
      "created": "2017-01-02T20:26:53.464Z",
      "updated": "2017-01-02T20:26:53.464Z"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/<account>"
        },
        "data": {
          "type": "accounts",
          "id": "<account>"
        }
      },
      "bearer": {
        "links": {
          "related": "/v1/accounts/<account>/products/31339351-f7f5-4bdd-8346-5d8399a1ac07"
        },
        "data": {
          "type": "products",
          "id": "31339351-f7f5-4bdd-8346-5d8399a1ac07"
        }
      }
    }
  }
}
```

--------------------------------

### Fetch relay install script with curl

Source: https://keygen.sh/docs/api/engines

Example request using curl to retrieve the latest relay install script. The URL contains a placeholder for the account and the Authorization header uses a bearer token.

```bash
curl https://raw.pkg.keygen.sh/<account>/relay/latest/install.sh \
  -H 'Authorization: Bearer <token>'
```

--------------------------------

### GET /v1/accounts/<account>/machines

Source: https://keygen.sh/docs/api/machines

Example request to list machines for an account using the Keygen API.

```APIDOC
## [GET] /v1/accounts/<account>/machines

### Description
List all machines for an account. This endpoint returns a paginated list of machines, with support for a limit query parameter.

### Method
GET

### Endpoint
https://api.keygen.sh/v1/accounts/<account>/machines

### Parameters
#### Path Parameters
- **account** (string) - Required - The account identifier.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of machines to return (e.g., 15).

### Request Example
```
curl https://api.keygen.sh/v1/accounts/<account>/machines?limit=15 -g \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **data** (array) - List of machine objects.
- **errors** (array) - Any errors encountered.

#### Response Example
```json
{
  "data": [],
  "errors": []
}
```
```

--------------------------------

### Install with --index-url and license authentication

Source: https://keygen.sh/docs/api/engines

Install a package using the PyPI engine with license authentication. The --index-url flag is preferred over --extra-index-url for security reasons.

```bash
pip install <package> \
  --index-url https://license:<key>@pypi.pkg.keygen.sh/<account>/simple
pip install <package> \
  --index-url https://license:<key>@pypi.pkg.keygen.sh/<account>/simple
```

--------------------------------

### GET /v1/accounts/<account>/processes

Source: https://keygen.sh/docs/api/processes

Example request to list processes for an account, with a limit query parameter.

```APIDOC
## [GET] /v1/accounts/<account>/processes

### Description
List processes for an account. This endpoint returns a collection of processes, with support for pagination via the `limit` query parameter.

### Method
GET

### Endpoint
https://api.keygen.sh/v1/accounts/<account>/processes

### Parameters
#### Path Parameters
- **account** (string) - Required - The account identifier.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of processes to return.

### Request Example
```
curl https://api.keygen.sh/v1/accounts/<account>/processes?limit=15 -g \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **data** (array) - List of process objects.

#### Response Example
```json
{
  "data": []
}
```
```

--------------------------------

### Install gem with --source and license authentication

Source: https://keygen.sh/docs/api/engines

Installs a gem using the `--source` flag with license authentication. Replace `<key>` with your license key and `<account>` with your account identifier or slug.

```bash
gem install union_of --source https://license:<key>@rubygems.pkg.keygen.sh/<account>
gem install union_of --source https://license:<key>@rubygems.pkg.keygen.sh/<account>
```

--------------------------------

### Create environment with cpprest (C++)

Source: https://keygen.sh/docs/api/environments

C++ example using cpprest to create an environment. Builds a JSON body with isolationStrategy, name, and code, then sends a POST request.

```cpp
#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 web::json;
using namespace utility;

http_client client("https://api.keygen.sh/v1/accounts/<account>");
http_request req;

value attrs;
attrs["isolationStrategy"] = value::string("SHARED");
attrs["name"] = value::string("QA Environment");
attrs["code"] = value::string("qa");

value data;
data["type"] = value::string("environments");
data["attributes"] = attrs;

value body;
body["data"] = data;

req.headers().add("Authorization", "Bearer <token>");
req.headers().add("Content-Type", "application/vnd.api+json");
req.headers().add("Accept", "application/json");

req.set_request_uri("/environments");
req.set_method(methods::POST);
req.set_body(body.serialize());

client.request(req)
  .then([](http_response res)
  {
    auto data = res.extract_json().get();
  })
  .wait();
```

--------------------------------

### Example request in C# (RestSharp)

Source: https://keygen.sh/docs/api/sandbox

Sends a GET request to the licenses endpoint with the sandbox environment header.

```csharp
using RestSharp;

var client = new RestClient("https://api.keygen.sh/v1/accounts/<account>");
var request = new RestRequest("licenses", Method.GET);

request.AddHeader("Keygen-Environment", "sandbox");
request.AddHeader("Accept", "application/vnd.api+json");
request.AddHeader("Authorization", "Bearer <token>");

var response = client.Execute(request);
```
Tokens:
Raw