runtime_keygen_sdk

Description:

runtime keygen sdk

runtime_keygen_sdk #
Dart SDK for Keygen
Overview #
Keygen is a fair source software licensing and distribution API. This package is meant to be used on the server and the
client. Most actions in the Keygen API are supported.
Getting started with Keygen
Introduction to the Keygen API
Uses #
This package will be useful for Dart applications that want to use Keygen for software licensing or distribution.
Supported platforms #
All platforms that can use the http package are supported.
Installation #
To add runtime_keygen_sdk to your Dart package, include it in your pubspec.yaml file:
dependencies:
runtime_keygen_sdk: ^1.0.0
copied to clipboard
Setup #
In order to use the Dart SDK for Keygen, you must first create a Keygen account.
Follow the instructions for Getting Started and take note of your:

Keygen AccountID
Admin Email
Admin Password

Example #
Here is a pseudocode example of calling the Keygen API.
Note that this example will NOT work out-of-the-box.
KeygenClient client = KeygenClient('<accountId>');

KeygenLicensesApi licensesApi = KeygenLicensesApi(client);

License license = await licensesApi.createLicense(
token: token,
policy: policy,
user: user
);
copied to clipboard
Tests #
Create a .env file and place it in the root of the package.
The .env file needs to contain the Keygen AccountID, Admin Email, and Admin Password, specified like this:
KEYGEN_ACCOUNTID=<accountid>
KEYGEN_ADMIN_EMAIL=<email>
KEYGEN_ADMIN_PASSWORD=<password>
copied to clipboard
Then you can run:
dart test
copied to clipboard
Why are there so many calls to await Future.delayed(wait); in the tests? #
Keygen enforces Rate Limiting and the delays are intended to prevent
extraneous load.
These calls need to be in-between API calls; simply putting delays in setUp and tearDown is not sufficient.
Supported actions #
Most actions in the Keygen API are supported, but not all.
The Keygen API can be divided into a few different categories:

Tokens
Products
Entitlements
Policies
Users
Licences
Machines
Miscellaneous

Tokens are used by Keygen for authenticating API requests.
Products are used to segment policies and licenses, in the case where you sell multiple products. This allows you to
keep licenses and policies between multiple products organized.
Entitlements can be attached to policies and to licenses to grant named "permissions" for things such as application
features. Entitlements can be attached to the following resources:

Policies: Any entitlement attached to a policy will automatically be attached to all licenses which implement the given policy.
Licenses: Entitlements attached to a license are one-off and only apply to that specific license resource.
Releases: Entitlements can be attached to releases through constraints, in order to assert that a given licensee possesses the necessary entitlements before being allowed to access a release's artifacts.

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.
Users represent an identity for an end-user, or licensee, of your software.
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.
Machines can be used to track and manage where your users are allowed to use your product.
There are other less common categories as well:

Components
Environments
Processes
Distribution

Components are hardware components for machines.
Environments can be created to segment your Keygen resources into buckets, for example, for an isolated sandbox
environment, or a shared production environment.
Processes are concurrent processes across machines.
Distribution is the distribution and updating of software via Keygen.
Below are tables that outline which actions are implemented for each category, as well as what tests exist and where
the actions fit in the Client / Server dichotomy.
TLDR:

User actions and License actions (except validating and checking-in) will run on server-side.
License validating, license checking-in, and Machine actions will run on client-side.

NOTE: Not every action will be executed client-side or server-side. Some actions (e.g. createProduct) are only
executed during initial setup and are not executed during regular client / server interaction.



Token Actions
Implemented
Tests
Client / Server




createToken
✅
✅



retrieveToken
✅
✅



regenerateToken
✅
✅



revokeToken
✅
✅



listTokens
✅
✅







Product Actions
Implemented
Tests
Client / Server




createProduct
✅
✅
One time only


retrieveProduct
✅
✅



updateProduct
✅
✅



deleteProduct
✅
✅



listProducts
✅
✅



createProductToken
✅
✅







Entitlement Actions
Implemented
Tests
Client / Server




createEntitlement
✅
✅
One time only


retrieveEntitlement
✅
✅



updateEntitlement
✅
✅



deleteEntitlement
✅
✅



listEntitlements
✅
✅







Policy Actions
Implemented
Tests
Client / Server




createPolicy
✅
✅
One time only


retrievePolicy
✅
✅



updatePolicy
✅
✅



deletePolicy
✅
✅



listPolicies
✅
✅



attachPolicyEntitlements
✅
✅



detachPolicyEntitlements
✅
✅



listEntitlements
✅
✅







User Actions
Implemented
Tests
Client / Server




createUser
✅
✅



retrieveUser
✅
✅



updateUser
✅
✅



deleteUser
✅
✅



listUsers
✅
✅



updatePassword
✅
✅



resetPassword
✅
📧



banUser
✅
✅



unbanUser
✅
✅



createUserToken
✅
✅



changeGroup
❌
❌
❌


addSecondFactor
❌
❌
❌


retrieveSecondFactor
❌
❌
❌


updateSecondFactor
❌
❌
❌


deleteSecondFactor
❌
❌
❌


listSecondFactors
❌
❌
❌






License Actions
Implemented
Tests
Client / Server




createLicense
✅
✅
Server


retrieveLicense
✅
✅
Server


updateLicense
✅
✅
Server


deleteLicense
✅
✅
Server


listLicenses
✅
✅
Server


validateLicenseByID
✅
✅



validateLicenseByKey
✅
✅
Client


suspendLicense
✅
✅
Server


reinstateLicense
✅
✅
Server


renewLicense
✅
✅
Server


revokeLicense
✅
✅
Server


checkOutLicense
❌
❌
❌


checkInLicense
✅
✅
Client


incrementUsage
❌
❌
❌


decrementUsage
❌
❌
❌


resetUsage
❌
❌
❌


createLicenseToken
✅
✅
Server


attachUsers
🐛
🐛
Server


detachUsers
🐛
🐛
Server


listUsers
🐛
🐛
Server


attachEntitlements
✅
✅
Server


detachEntitlements
✅
✅
Server


listEntitlements
✅
✅
Server


changeLicensePolicy
✅
✅
Server


changeOwner
❌
❌
❌


changeGroup
❌
❌
❌






Machine Actions
Implemented
Tests
Client / Server




activateMachine
✅
✅
Client


retrieveMachine
✅
✅
Client


updateMachine
✅
✅
Client


deactivateMachine
✅
✅
Client


listAllMachines
✅
✅
Client


checkOutMachine
❌
❌
❌


pingHeartbeat
✅
✅
Client


resetHeartbeat
✅
✅
Client


changeOwner
🐛
🐛
Server


changeGroup
❌
❌
❌






Miscellaneous Actions
Implemented
Tests
Client / Server




whoAmI
🐛
🐛
Client / Server


forgotPassword
✅
📧




Legend #
🐛 = bug in generated OpenAPI code from runtime_keygen_openapi package
whoAmI currently throws exception when called with license token or product token.
license attachUsers is currently missing from OpenAPI .yml file from runtime_keygen_openapi package.
license detachUsers is currently missing from OpenAPI .yml file from runtime_keygen_openapi package.
license listUsers is currently missing from OpenAPI .yml file from runtime_keygen_openapi package.
machine changeOwner is currently missing from OpenAPI .yml file from runtime_keygen_openapi package.
❌ = not planned to be supported (but may be re-evaluated)
📧 = requires reading email
The remaining groups of actions are not supported:

Components: not yet specified in OpenAPI spec file
Environments: not planned to be supported (but may be re-evaluated)
Processes: not planned to be supported (but may be re-evaluated)
Distribution: not planned to be supported (but may be re-evaluated)

Workflows #
There are several common scenarios when using Keygen. These involve interacting with the client application, possibly
some intermediary server, possibly the user's email, and Keygen itself.
One time: #
Various actions may only need to be done once, and may be done from the Keygen dashboard.
Some of these actions are:

Create a product
Create entitlements
Create a policy

When creating a policy, you may want to specify the strategy to use for matching components. You can do that with these
attributes:
requireComponentsScope = true
componentMatchingStrategy = MATCH_ANY, MATCH_TWO, MATCH_MOST, MATCH_ALL
copied to clipboard
Workflow: Creating a license #

Pseudocode for the client application would be:
1. start the application with no license key
2. send user credentials to intermediary server, and ask to create a new license
3. application receives license key from intermediary server
4. application stores license key
copied to clipboard
Pseudocode for the intermediary server would be:
1. receive request from application to create license
2. contact Auth0 to obtain user_id
3. send /createLicense request to Keygen
4. receive response from Keygen with license key and license id
5. send /updateLicense request to Keygen, with license id and Auth0 user_id to store in metadata
6. send license key to application
copied to clipboard
Workflow: Activating a machine #

Pseudocode for the client application would be:
1. get machine id and other component fingerprints
2. ask intermediary server to activate the machine, and send license key and component fingerprints
3. receive response from intermediary server that machine is activated
copied to clipboard
Pseudocode for the intermediary server would be:
1. receive request from application to activate machine with various fingerprints
2. send /whoAmI to Keygen with license key
3. receive license id
4. send /activateMachine to Keygen with license id and machine fingerprint
5. receive machine id
6. send /addComponent to Keygen with machine id and component fingerprints
7. send machine activation to application
copied to clipboard
Workflow: Validating a license #

Pseudocode for the client application would be:
1. determine that it is time to validate license
2. send request to validate to intermediary server, with license key and fingerprints
3. receive validation from server
copied to clipboard
Pseudocode for the intermediary server would be:
1. receive request for validation from application, with license key and fingerprints
2. send /validateLicenseKey to Keygen, with license key and fingerprints
3. receive validation from Keygen
4. send validation to application
copied to clipboard
Caveats #
Updating metadata #
Since the metadata attribute is simply a key-value store (object), all write operations will overwrite the entire
object, so be sure to merge existing data on your end when performing updates.
Metadata is not inheritable.
https://keygen.sh/docs/api/metadata/
https://github.com/orgs/keygen-sh/discussions/106
Implementation details #
Modifications from generated OpenAPI code #
This package uses runtime_keygen_openapi, which includes generated OpenAPI code.
OpenAPI defines some parameters as Object? metadata, but these have been modified to be Map<String, String>? metadata.
OpenAPI defines some parameters as Object? page, but these have been modified to be Map<String, int>? page.