Feature licenses and using our new entitlements system

[ezekg]

We recently rolled out a new entitlements system, making feature licenses even easier to implement. In the past, you'd need to add key-value pairs to a license's metadata, which can become error prone and also be a headache when launching a new feature flag that needs to be added or backfilled to a large subset of licenses.

What we've done is add a new entitlement object, which can be attached to policies and licenses.

An entitlement object looks like this:

{
  "data": {
    "id": "db1ff21b-f42f-4623-952b-ca7f2600bded",
    "type": "entitlements",
    "attributes": {
      "name": "Example Feature",
      "code": "EXAMPLE_FEATURE",
      "metadata": {},
      "created": "2021-04-22T17:00:00.000Z",
      "updated": "2021-04-22T17:00:00.000Z"
    },
    "relationships": {
      "account": {
        "links": {
          "related": "/v1/accounts/1fddcec8-8dd3-4d8d-9b16-215cac0f9b52"
        },
        "data": {
          "type": "accounts",
          "id": "1fddcec8-8dd3-4d8d-9b16-215cac0f9b52"
        }
      }
    },
    "links": {
      "self": "/v1/accounts/1fddcec8-8dd3-4d8d-9b16-215cac0f9b52/entitlements/db1ff21b-f42f-4623-952b-ca7f2600bded"
    }
  }
}

The most important part of an entitlement is it's code attribute. These codes can be utilized within your software application to check if a license is entitled to do something. For example, you could have an entitlement with code PRO_FEATURES, then within your software you could do something like this:

const entitlements = await listEntitlementsForLicense(license.id)
if (entitlements.includes('PRO_FEATURES')) {
  performProFeature()
}

Entitlements can be attached to policies and also to licenses. When an entitlement is attached to a policy, all licenses that 'implement' that particular policy will automatically inherit the policy's entitlements. You can attach one-off entitlements to licenses directly.

For entitlements that are "table-stakes", i.e. required entitlements, you can include those entitlement codes inside of a validation request using the new entitlements scope:

curl -X POST https://api.keygen.sh/v1/accounts/1fddcec8-8dd3-4d8d-9b16-215cac0f9b52/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",
          "scope": {
            "entitlements": [
              "RUN_APPLICATION_V1"
            ]
          }
        }
      }'

Entitlements can also be used with Keygen Dist to manage things such as version entitlements. For example, when you go from v1 to a v2 release of your software, you may not want to let users that didn't upgrade their license to download and use v2 until they purchase an updated license. In this scenario, you would create a APP_V1 entitlement and an APP_V2 entitlement. Then, within your auto-updater code, you'd want to add the entitlement assertion to the update URL:

https://dist.keygen.sh/v1/demo/update/macos/zip/v2.0.0?entitlement=APP_V2

We're excited to see what people build with the new entitlements system.

Happy to answer any questions here!