Getting Started with our API

Learn how to create a product and a basic license policy, as well as a license using Keygen's 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.


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.

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.

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,
       "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 (except for encrypted licenses). When the key attribute is left blank, a key will automatically be generated for you whenever the license is created.

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,
       "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


Next steps

That's it! 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.

Next up, you could…

We also have a collection of examples on our GitHub, which covers things such as:

Questions? Reach out at [email protected].