menu
Select programming language for code examples

linkAPI reference

The Keygen API is organized around REST principles. All requests must be made over TLS/SSL. We only support TLS 1.2+, for security reasons. All API request and response bodies, including errors, are encoded in JSON format.

The API has predictable, resource-oriented URLs, and uses standard HTTP response codes to indicate API errors. We use built-in HTTP features, like authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from any client-facing software application.

code Get Started with our API

linkYour account

In order to make requests to our licensing API, you will need to use your Keygen account's unique ID, or its slug that you chose during sign up. Every API request will utilize your account's ID or slug within the URL path, i.e. /v1/accounts/<id> or /v1/accounts/<slug>. Your account's ID and slug can be used interchangeably as URL params.

You can find your account's ID and slug in your account settings, under the "Current Account" section.

Protected vs unprotected

An unprotected Keygen account will allow public user registration, user token generation (authentication), and will also allow users to create their own licenses and machines while authenticated. This is referred to as an "unprotected" account, allowing client-side resource management (i.e. by your users), while you respond to those events using webhooks.

For example, you can allow users to create and delete their own licenses and machines, while you handle to those events for billing purposes, e.g. charge them for new licenses, update their subscription to match their license and machine count, etc.

If you do not want your users to be able to create and manage their own licenses and machines client-side (which may necessitate listening for webhook events) then you should set your account to "protected", which will require admin authentication to create and manage all resources, aside from machine activation and deactivation.

By default, your account is set to protected. You can change that from your account settings page.

See the security section for more tips.

linkContent types

Our JSON API accepts the following content types specified via the HTTP Content-Type header:

  • application/vnd.api+json
  • application/json

In addition, our JSON API is able to respond with the following content types specified via the HTTP Accept header:

  • application/vnd.api+json
  • application/json

By default our API will respond with application/vnd.api+json, unless asked otherwise through the standard HTTP Accept header. All other content types will be rejected with a 400 status code.

linkClient libraries

At the moment we're laser-focused on our HTTP API endpoints. As time goes by we'll be featuring here some more of our open source clients for different languages and frameworks, as well as those contributed by the community.

Official SDKs

Language
Go keygen-go (our reference SDK)

Open Source

If you've written an open source integration or client library, SDK, or other integration yourself, please let us know. We will feature your name along with a link to the client library, unless asked to do otherwise.

Integration
Rust keygen-rs by ahonn
Node electron-builder by develar and mmaietta
Tauri tauri-plugin-keygen by bagindo
GitHub Actions keygen-action by getgrit
OpenAPI Spec keygen-openapi by eugeniodepalo
We will collaborate with project maintainers to keep open source libraries up-to-date as our systems evolve. If you would like us to add documentation examples for a specific language, or if you would like us to add an open source library you created, please email [email protected].

HTTP libraries

Integrating Keygen is easy using any standard HTTP library. In our docs and in sample apps, we use the following open source HTTP libraries:

Language
Node node-fetch by bitinn
Python Requests by psf
Swift Alamofire
C# RestSharp
Kotlin Unirest by mashape
Java Unirest by mashape
C++ C++ REST SDK by Microsoft
Shell cURL

You may of course choose to use a different HTTP library, but these are the libraries that you will see used throughout our documentation.