menu
 

Getting Started

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.

lock

Choosing a Licensing Model

Review the types of license models Keygen supports. Learn how to integrate perpetual and timed licenses, floating licenses and more.

keyboard_arrow_right

Included on this page:

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.

Electron Framework

Examples of adding license keys and auto-updates to Electron apps

keyboard_arrow_right

Node Programming Language

Examples for adding license keys to a Node or JavaScript application

keyboard_arrow_right

Python Programming Language

Examples of adding licensing to software written in Python

keyboard_arrow_right

C# Programming Language

Examples of adding licence key validation to various C# applications

keyboard_arrow_right

PHP Programming Language

Examples for adding license keys to various PHP programs including WordPress plugins or themes

keyboard_arrow_right

Rust Programming Language

Examples of how to integrate Keygen's software licensing API into a Rust program

keyboard_arrow_right

Go Programming Language

Examples for integrating Keygen's software licensing and distribution APIs into a Go application

keyboard_arrow_right

C++ Programming Language

Examples of how to securely add licensing to various C and C++ applications

keyboard_arrow_right

Shell Environment

Examples how to interface with Keygen's licensing APIs using Bash

keyboard_arrow_right

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"
           }
         }
       }'
Example Response
 {
   "data": { ...
     "id": "6b5bb5a3-0e32-4226-88fd-86a97ecd0678",
     "type": "products",
     "attributes": {
       "name": "Example Product",
       "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>"
         }
       },
       "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"
               }
             }
           }
         }
       }'
Example Response
 {
   "data": { ...
     "id": "d888f7db-ad63-44f2-aa62-a7f2936d65d3",
     "type": "policies",
     "attributes": {
       "name": "Example Policy",
       "duration": null,
       "floating": false,
       "maxMachines": 1,
       "maxProcesses": null,
       "maxUsers": null,
       "maxCores": null,
       "maxUses": null,
       "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>"
         }
       },
       "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": "2022-03-15T19:27:50.440Z"
           },
           "relationships": {
             "policy": {
               "data": {
                 "type": "policy",
                 "id": "d888f7db-ad63-44f2-aa62-a7f2936d65d3"
               }
             }
           }
         }
       }'
Example Response
 {
   "data": { ...
     "id": "5948271a-28b9-4615-96e9-9363282cab58",
     "type": "licenses",
     "attributes": {
       "name": null,
       "key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
       "expiry": "2022-03-15T19:27:50.440Z",
       "status": "ACTIVE",
       "uses": 0,
       "suspended": false,
       "version": "1.0.0",
       "floating": false,
       "maxMachines": 1,
       "maxProcesses": null,
       "maxUsers": null,
       "maxCores": null,
       "maxUses": null,
       "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>"
         }
       },
       "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"
         }
       },
       "owner": {
         "links": {
           "related": "/v1/accounts/<account>/licenses/5948271a-28b9-4615-96e9-9363282cab58/owner"
         },
         "data": null
       },
       "users": {
         "links": {
           "related": "/v1/accounts/<account>/licenses/5948271a-28b9-4615-96e9-9363282cab58/users"
         },
         "meta": {
           "count": 0
         }
       },
       "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"
         }
       }'
Example Response
 {
   "data": { ...
     "id": "5948271a-28b9-4615-96e9-9363282cab58",
     "type": "licenses",
     "attributes": {
       "name": null,
       "key": "C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3",
       "expiry": "2022-03-15T19:27:50.440Z",
       "status": "ACTIVE",
       "uses": 0,
       "suspended": false,
       "floating": false,
       "version": "1.0.0",
       "maxMachines": 1,
       "maxProcesses": null,
       "maxUsers": null,
       "maxCores": null,
       "maxUses": null,
       "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>"
         }
       },
       "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"
         }
       },
       "owner": {
         "links": {
           "related": "/v1/accounts/<account>/licenses/5948271a-28b9-4615-96e9-9363282cab58/owner"
         },
         "data": null
       },
       "users": {
         "links": {
           "related": "/v1/accounts/<account>/licenses/5948271a-28b9-4615-96e9-9363282cab58/users"
         },
         "meta": {
           "count": 0
         }
       },
       "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",
     "code": "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].