Getting Started with our API

Learn how to create a product and a basic policy, as well as a license using Keygen's software licensing API. All code example can be executed using curl. If you need help after reading this, reach out to our technical support.

To get started, you will either need to log into your Dashboard or generate an authentication token via the API. To generate a token directly through the API, check out the code examples in the API reference, which includes examples in popular languages like Swift, C# and JavaScript.


Example Applications

Below you can find a variety of language-specific example applications on our GitHub account. Not seeing what you're looking for? Please reach out — we'd love to help.


The Basics

Below we'll cover the basic API resources for your Keygen account.

Your Keygen Account

In order to make requests to our licensing API, you will need to use your Keygen account's unique ID. Every API request must include your account's ID within the URL path, i.e. /v1/accounts/{ID}.

Not sure what your account ID is? You can find your account ID in your account settings, under the "Current Account" section. We will also pre-populate your account ID and API token in the code examples below.

Creating a Product

The product resource is used to segment policies and licenses by product, in the case where you sell multiple products. This allows you to keep licenses and policies between multiple products organized. If you don't sell more than 1 product, this will be a one-time step.

Example Request

 curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/products \
   -H 'Authorization: Bearer <%= token %>' \
   -H 'Content-Type: application/vnd.api+json' \
   -H 'Accept: application/vnd.api+json' \
   -d '{
         "data": {
           "type": "product",
           "attributes": {
             "name": "Example Product"
           }
         }
       }'
View Example Response
{
   "data": {
     "id": "6b5bb5a3-0e32-4226-88fd-86a97ecd0678",
     "type": "products",
     "attributes": {
       "name": "Example Product",
       "metadata": {},
       "created": "<%= created %>",
       "updated": "<%= created %>"
     },
     "relationships": {
       "account": {
         "links": {
           "related": "/v1/accounts/<%= account %>"
         },
         "data": {
           "type": "accounts",
           "id": "<%= account %>"
         }
       },
       "policies": {
         "links": {
           "related": "/v1/accounts/<%= account %>/products/6b5bb5a3-0e32-4226-88fd-86a97ecd0678/policies"
         }
       },
       "licenses": {
         "links": {
           "related": "/v1/accounts/<%= account %>/products/6b5bb5a3-0e32-4226-88fd-86a97ecd0678/licenses"
         }
       },
       "machines": {
         "links": {
           "related": "/v1/accounts/<%= account %>/products/6b5bb5a3-0e32-4226-88fd-86a97ecd0678/machines"
         }
       },
       "users": {
         "links": {
           "related": "/v1/accounts/<%= account %>/products/6b5bb5a3-0e32-4226-88fd-86a97ecd0678/users"
         }
       },
       "tokens": {
         "links": {
           "related": "/v1/accounts/<%= account %>/products/6b5bb5a3-0e32-4226-88fd-86a97ecd0678/tokens"
         }
       }
     },
     "links": {
       "self": "/v1/accounts/<%= account %>/products/6b5bb5a3-0e32-4226-88fd-86a97ecd0678"
     }
   }
 }

View Product resource in the API reference


Creating a Policy

Next, we're going to add a license policy for your product. License policies define the different "types" of licenses that your product offers. Policies can be for a number of different things, from different "tiers" for your product (e.g. Basic vs Pro) to fine-grained feature policies.

Learn how to set up a policy that meets your licensing requirements by reviewing our guide on choosing a licensing model.

Example Request

 curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/policies \
   -H 'Authorization: Bearer <%= token %>' \
   -H 'Content-Type: application/vnd.api+json' \
   -H 'Accept: application/vnd.api+json' \
   -d '{
         "data": {
           "type": "policy",
           "attributes": {
             "name": "Example Policy"
           },
           "relationships": {
             "product": {
               "data": {
                 "type": "product",
                 "id": "6b5bb5a3-0e32-4226-88fd-86a97ecd0678"
               }
             }
           }
         }
       }'
View Example Response
{
   "data": {
     "id": "d888f7db-ad63-44f2-aa62-a7f2936d65d3",
     "type": "policies",
     "attributes": {
       "name": "Example Policy",
       "duration": null,
       "floating": false,
       "maxMachines": 1,
       "maxCores": null,
       "maxUses": null,
       "metadata": {},
       "created": "<%= created %>",
       "updated": "<%= created %>"
     },
     "relationships": {
       "account": {
         "links": {
           "related": "/v1/accounts/<%= account %>"
         },
         "data": {
           "type": "accounts",
           "id": "<%= account %>"
         }
       },
       "product": {
         "links": {
           "related": "/v1/accounts/<%= account %>/policies/d888f7db-ad63-44f2-aa62-a7f2936d65d3/product"
         },
         "data": {
           "type": "products",
           "id": "6b5bb5a3-0e32-4226-88fd-86a97ecd0678"
         }
       },
       "pool": {
         "links": {
           "related": "/v1/accounts/<%= account %>/policies/d888f7db-ad63-44f2-aa62-a7f2936d65d3/pool"
         }
       },
       "licenses": {
         "links": {
           "related": "/v1/accounts/<%= account %>/policies/d888f7db-ad63-44f2-aa62-a7f2936d65d3/licenses"
         }
       }
     },
     "links": {
       "self": "/v1/accounts/<%= account %>/policies/d888f7db-ad63-44f2-aa62-a7f2936d65d3"
     }
   }
 }

View Policy resource in the API reference


Creating a License

The license resource is what you'd expect—licenses are used to grant access to your software. Each license resource will implement a policy, which will define the "rules" which that license must follow to remain valid. Each license can be associated with a user, but that's optional; this is useful when you're associating multiple licenses with a single user.

When creating a new license, you have the option to manually specify a license key. When the key attribute is left blank, a key will automatically be generated for you whenever a new license is created.

Example Request

 curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/licenses \
   -H 'Authorization: Bearer <%= token %>' \
   -H 'Content-Type: application/vnd.api+json' \
   -H 'Accept: application/vnd.api+json' \
   -d '{
         "data": {
           "type": "license",
           "attributes": {
             "expiry": "<%= expiry %>"
           },
           "relationships": {
             "policy": {
               "data": {
                 "type": "policy",
                 "id": "d888f7db-ad63-44f2-aa62-a7f2936d65d3"
               }
             }
           }
         }
       }'
View Example Response
{
   "data": {
     "id": "5948271a-28b9-4615-96e9-9363282cab58",
     "type": "licenses",
     "attributes": {
       "name": null,
       "key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
       "expiry": "<%= expiry %>",
       "uses": 0,
       "suspended": false,
       "floating": false,
       "maxMachines": 1,
       "maxCores": null,
       "maxUses": null,
       "metadata": {},
       "created": "<%= created %>",
       "updated": "<%= created %>"
     },
     "relationships": {
       "account": {
         "links": {
           "related": "/v1/accounts/<%= account %>"
         },
         "data": {
           "type": "accounts",
           "id": "<%= account %>"
         }
       },
       "product": {
         "links": {
           "related": "/v1/accounts/<%= account %>/licenses/5948271a-28b9-4615-96e9-9363282cab58/product"
         },
         "data": {
           "type": "products",
           "id": "6b5bb5a3-0e32-4226-88fd-86a97ecd0678"
         }
       },
       "policy": {
         "links": {
           "related": "/v1/accounts/<%= account %>/licenses/5948271a-28b9-4615-96e9-9363282cab58/policy"
         },
         "data": {
           "type": "policies",
           "id": "d888f7db-ad63-44f2-aa62-a7f2936d65d3"
         }
       },
       "user": {
         "links": {
           "related": "/v1/accounts/<%= account %>/licenses/5948271a-28b9-4615-96e9-9363282cab58/user"
         },
         "data": null
       },
       "machines": {
         "links": {
           "related": "/v1/accounts/<%= account %>/licenses/5948271a-28b9-4615-96e9-9363282cab58/machines"
         },
         "meta": {
           "count": 0
         }
       },
       "tokens": {
         "links": {
           "related": "/v1/accounts/<%= account %>/licenses/5948271a-28b9-4615-96e9-9363282cab58/tokens"
         }
       }
     },
     "links": {
       "self": "/v1/accounts/<%= account %>/licenses/5948271a-28b9-4615-96e9-9363282cab58"
     }
   }
 }

View License resource in the API reference


Validating a License Key

Validating a license key from within your application's code is simple — all you have to do is send the license key to the validate-key API endpoint. The response will include the license validation result, as well as the full license object for subsequent requests, such as device activation.

When validating license, you have the option of specifying validation scopes for the request. You can use this to scope the validation to specific machines, products, and more. For example, scoping to a machine fingerprint will not only check that the license is "valid" but it will check if the license is valid for that specific machine fingerprint.

Example Request

 curl -X POST https://api.keygen.sh/v1/accounts/<%= account %>/licenses/actions/validate-key \
   -H 'Content-Type: application/vnd.api+json' \
   -H 'Accept: application/vnd.api+json' \
   -d '{
         "meta": {
           "key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3"
         }
       }'
View Example Response
{
   "data": {
     "id": "5948271a-28b9-4615-96e9-9363282cab58",
     "type": "licenses",
     "attributes": {
       "name": null,
       "key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
       "expiry": "<%= expiry %>",
       "uses": 0,
       "suspended": false,
       "floating": false,
       "maxMachines": 1,
       "maxCores": null,
       "maxUses": null,
       "metadata": {},
       "created": "<%= created %>",
       "updated": "<%= created %>"
     },
     "relationships": {
       "account": {
         "links": {
           "related": "/v1/accounts/<%= account %>"
         },
         "data": {
           "type": "accounts",
           "id": "<%= account %>"
         }
       },
       "product": {
         "links": {
           "related": "/v1/accounts/<%= account %>/licenses/5948271a-28b9-4615-96e9-9363282cab58/product"
         },
         "data": {
           "type": "products",
           "id": "6b5bb5a3-0e32-4226-88fd-86a97ecd0678"
         }
       },
       "policy": {
         "links": {
           "related": "/v1/accounts/<%= account %>/licenses/5948271a-28b9-4615-96e9-9363282cab58/policy"
         },
         "data": {
           "type": "policies",
           "id": "d888f7db-ad63-44f2-aa62-a7f2936d65d3"
         }
       },
       "user": {
         "links": {
           "related": "/v1/accounts/<%= account %>/licenses/5948271a-28b9-4615-96e9-9363282cab58/user"
         },
         "data": null
       },
       "machines": {
         "links": {
           "related": "/v1/accounts/<%= account %>/licenses/5948271a-28b9-4615-96e9-9363282cab58/machines"
         },
         "meta": {
           "count": 0
         }
       },
       "tokens": {
         "links": {
           "related": "/v1/accounts/<%= account %>/licenses/5948271a-28b9-4615-96e9-9363282cab58/tokens"
         }
       }
     },
     "links": {
       "self": "/v1/accounts/<%= account %>/licenses/5948271a-28b9-4615-96e9-9363282cab58"
     }
   },
   "meta": {
     "ts": "2021-03-29T17:47:17.957Z",
     "valid": true,
     "detail": "is valid",
     "constant": "VALID"
   }
 }

View the key validation action in the API reference


Next steps

That's the basics! Now that you've got a product all set up with a license policy and your first license, you're all set to start integrating Keygen into your software product. Other API resources to look at: machines and users.

But first, explore the various licensing models we support.

Choose a License Model

Questions? Reach out at [email protected].