Skip to main content

New Licensing Mechanism in 3.1.1

· 4 min read
Jeremy Scott
Co-founder

Licensing changed substantially in opscotch 3.1.1.

The previous embedded license model still works in 3.1.1, but the recommended model is now hierarchical runtime licensing. Licenses are issued through https://licensing.opscotch.co, can be delegated down a chain of authority, and can be managed without rebuilding packages.

The previous licensing model required you to embed an expiring license in each distributed package. Licensing was therefore a build-time concern. Updating entitlements often meant rebuilding and redeploying packages, and tracking expiry across many packaged apps was operationally awkward.

How the current licensing model works

Licenses now flow down a chain of authority:

ROOT → ISSUER → VENDOR → ORG → PLATFORM → RUNTIME

  • Upstream parties can issue child licenses from parent licenses.
  • End-user organisations are typically issued at the ORG level.
  • Organisations create PLATFORM licenses.
  • A licensing app can hold one or more PLATFORM licenses and serve runtime licensing to other runtimes.
  • The runtime accepts RUNTIME or PLATFORM licenses.
  • Licenses are environment-specific: non-production licenses are valid only on non-production runtimes, and production licenses are valid only on production runtimes.

Licenses can still be embedded in packaged applications, but they no longer have to be.

Roles and flow

  • ISSUER and VENDOR parties can hold large parent licenses and delegate child licenses downstream.
  • ORG parties can create PLATFORM licenses for departments, environments, or individual development users.
  • PLATFORM licenses can be installed into the opscotch licensing app and used to serve runtime licensing.
  • RUNTIME licenses are the licenses consumed by the runtime when workloads start.

This model supports reseller, managed-service, and customer-managed operating models without requiring each package to carry its own long-lived embedded license.

License attributes

License metadata is attribute-based. Attributes are inherited by child licenses unless changed subject to the attribute rules.

Attributes can be:

  • string values
  • numeric values
  • boolean values
  • constrained values

Constraint examples include:

  • read-only attributes
  • directional attributes that only allow values to move in one direction downstream

For example:

  • issuedDateUTC is a read-only string attribute
  • expiryDateUTC can only be decreased when issuing a child license
  • credits is numeric when present and can only be reduced in child licenses

Not all licenses use credits. Some licenses are open and do not carry a credit balance.

Bootstrap: licensing host and pool

Runtimes can obtain runtime licensing from a licensing app:

{
  "licenseHost": "http://localhost:39576",
  "licenseHostPoolId": "my-dept-license-pool"
}
  • licenseHost is optional and defaults to the local licensing app
  • licenseHostPoolId selects the pool that holds the PLATFORM license used for runtime issuance

What changed compared with the old model

  • Old model: embed a license in the package and redeploy the package when licensing changes
  • Current model: issue hierarchical licenses through licensing.opscotch.co, manage runtime licensing centrally, and change entitlements without rebuilding packages

The old embedded model still works in 3.1.1, but it is now the legacy path and is planned for removal in the next release.

Issuing child licenses

Licenses are created through https://licensing.opscotch.co. They are not created directly by package builds or by arbitrary runtime endpoints.

The current child-license flow uses:

  • parentLicenseId
  • ownerKeyHex
  • licenseTo
  • optional metaData

ownerKeyHex replaces the older secretKeyHex and parentSecretKey terminology.

For the current request and response format, see the admin documentation:

Parent and child license data

When you work with an issued parent license, the important values are:

  • license
  • licenseId
  • ownerKeyHex
  • type
  • licenseTo
  • metadata

Common metadata includes:

  • env
  • issuedDateUTC
  • expiryDateUTC
  • role metadata such as issuer, vendor, org, or platform
  • credits, when the parent license is credit-constrained

After issuing a child license, retain:

  • license
  • licenseId
  • ownerKeyHex
  • metadata.expiryDateUTC

ownerKeyHex is returned only on the first successful issuance response for a given transaction and must be stored securely.

Operational benefits

  • No package rebuild is required to change licensing.
  • Issuers and vendors can delegate licenses downstream without manual repackaging.
  • Organisations can split and manage their own platform allocations.
  • Runtime licensing can be centralised in the licensing app.
  • Attribute-based metadata allows policy and constraints to flow with the license hierarchy.
  • Packages can still embed licenses when that deployment model is preferable.

The opscotch licensing app

The opscotch licensing app can be installed into an opscotch runtime and configured with one or more PLATFORM licenses.

Other runtimes can then obtain runtime licensing from it by setting licenseHost and, optionally, licenseHostPoolId.

For the operational details, request examples, and current field names, refer to: