What reaches your application
Some of the fields you set on a feature, a product, a plan, an add-on, a meter, an offer or an entitlement reach your customer’s software or your customer, and the rest stay in your portal and your admin API. A field that leaves goes to one or more of three places, and only one of them is signed.
Three destinations
Section titled “Three destinations”| Destination | What it is | What it can be used for |
|---|---|---|
| Signed license | The license token. Its claims, such as features, products, usage_limits, exp, lease and lic, are signed with your signing key. |
Enforcement. The application can rely on these values, because they can’t be changed on the device. |
| Sent to your application, not signed | The activation response around the token: the entitlement’s Description and LicenseTermsUrl, ActivatedFeatures, Products and Meters. |
Display only. It isn’t tamper-proof, and anyone with the device can read it. |
| Shown to your customer | Your customer’s license pages in the user portal, and the customer API behind them. | What your customer sees about their own license. |
In the portal, a small marker after a field’s label, or after a column heading, shows where that field goes. Each marker explains itself when you point at it:
- Green shield: in the signed license.
- Gray window: sent to your application, not signed.
- Blue person: shown to your customer.
- Crossed-out shield: normally in the signed license, but a setting keeps it out right now, such as In license switched off or a catalog entry that is Draft, Disabled or Archived.
A field with no marker stays in the portal and the admin API. License preview on an entitlement or an offer shows the complete result for that one grant.
Copies, not links
Section titled “Copies, not links”A product feature’s settings are copied onto an entitlement when the product is attached, and every field of an offer is copied onto an entitlement when one is ordered from it. Changing the product feature or the offer later doesn’t reach entitlements that already exist, and that includes In license. To change one customer’s license, change their entitlement.
A feature’s display name is copied too: the application gets the name as it was when the product was attached, while your customer’s pages show the current one.
A few things are read fresh every time a license is issued or refreshed instead: a catalog entry’s type, metric, units and Draft, Disabled or Archived status, a product’s name, version and custom properties, and the entitlement’s own fields, such as its description and license terms URL.
Feature catalog entry
Section titled “Feature catalog entry”| Field | Signed license | Sent to your application | Shown to your customer |
|---|---|---|---|
| Feature code | features[].code |
ActivatedFeatures[].FeatureCode |
Yes |
| Display name | No | ActivatedFeatures[].Name |
Yes |
| Feature type | features[].deny, for a Boolean whose value isn’t true |
ActivatedFeatures[].IsDenied |
No |
| Metric | The key in usage_limits |
ActivatedFeatures[].MetricName |
Yes |
| Units | No | ActivatedFeatures[].Units |
Yes, after the value |
| Status Draft, Disabled or Archived | Leaves the whole feature out | Leaves the whole feature out | No |
Units is a label for showing a value, such as GB or seats, so it isn’t signed. A true/false feature has none. Visibility, meter aggregation, value weight, tags and enum options stay in the portal. Visibility only decides whether your customer sees the feature on their license pages. An Internal feature can still be in the signed license, so your application can still check it.
Feature on a product version
Section titled “Feature on a product version”| Field | Signed license | Sent to your application | Shown to your customer |
|---|---|---|---|
| Description | No | ActivatedFeatures[].Description |
No |
| Module name | No | ActivatedFeatures[].ModuleName |
No |
| Value | features[].val |
ActivatedFeatures[].Value |
No |
| On by default | features[].enable |
ActivatedFeatures[].IsEnabled |
No |
| Available in trial | features[].trial |
ActivatedFeatures[].IsAvailableDuringTrialPeriod |
No |
| Available in grace | features[].grace |
ActivatedFeatures[].IsAvailableDuringGracePeriod |
No |
| Paid feature | features[].paid |
ActivatedFeatures[].IsPaidFeature |
No |
| In license | Off leaves the whole feature out | Still listed | Still listed |
In license switched off means your server enforces the feature, not the device. The feature leaves the signed license only: the activation response and your customer’s pages still list it as included, because your customer still owns it. Its code, value and description still reach the device unsigned, so a feature value is never a secret.
Whether the value can be changed on an entitlement, and the sort order, stay in the portal.
Product
Section titled “Product”| Field | Signed license | Sent to your application | Shown to your customer |
|---|---|---|---|
| Product code | products[].code |
Products[].ProductCode |
Yes |
| Product version | products[].ver |
Products[].ProductVersion |
Yes |
| Name | No | Products[].Name |
Yes |
| Custom properties | No | Products[].PropertyValues, the ones marked Public |
No |
A custom property is Private until you mark it Public, and a Private one stays in the
portal. The description, end of life, tags, external reference and allowed
applications stay in the portal too. The allowed applications and the end of life only
decide whether a device may activate.
The code and version are the only product fields that are signed. To check which version a
license covers, for example a 1.x license on a 2.0 build, read the signed products claim,
not the copy beside it.
Entitlement and offer
Section titled “Entitlement and offer”| Field | Signed license | Sent to your application | Shown to your customer |
|---|---|---|---|
| Name | No | No | Yes |
| Version | No | No | Yes |
| Description | No | Description |
Yes |
| License terms URL | No | LicenseTermsUrl |
Yes, as a License terms link |
| License key | No | No | Yes |
| Plan | Feature values, features[].deny and usage_limits |
ActivatedFeatures |
The plan name |
| Feature permitted, value, trial, grace, paid and expiry | features[].enable, val, trial, grace, paid, exp |
ActivatedFeatures[] |
No |
| License lease time | lease, lease_exp |
No | The lease end of each device |
| License grace period | grace_exp |
No | The grace end of each device |
| Time restriction and subscription | nbf, exp |
No | The expiry date and status |
| Trial | trial_exp, lic |
No | Whether it’s a trial, and when it ends |
| Anonymous try, on an offer | try and exp on the try licenses it issues |
No | No |
The order number, references, contact, metadata, tags, organization and billing stay in the portal. So do the seats, floating, offline activation, fingerprint matching, activation policy and activation key format: they decide whether a device may activate, and aren’t carried in the license.
A plan’s values are applied to an entitlement when the plan is assigned to it, and from then on reach the license the way the entitlement’s own feature values do. A later change to a value reaches an entitlement already on the plan when the plan is applied to it again. The plan listing your customer sees always shows the plan as it is now.
| Field | Signed license | Sent to your application | Shown to your customer |
|---|---|---|---|
| Feature value | features[].val |
ActivatedFeatures[].Value |
Yes |
| Denied | features[].deny |
ActivatedFeatures[].IsDenied |
Listed as Denied, with no value |
| Not included | Leaves the whole feature out | Leaves the whole feature out | Listed as Not included, with no value |
| Usage tiers | The highest tier end, in usage_limits |
No | The tiers, and the current tier’s limit |
| Name | No | No | Yes |
| Description | No | No | Yes |
| Sort order | No | No | The order the plans are listed in |
The price, currency and weight stay in the portal, and so do the plan set’s name and description. Your customer’s plan listing in the customer API shows a Denied or Not included feature with no value; their license pages leave it out.
Add-on and suite
Section titled “Add-on and suite”| Field | Signed license | Sent to your application | Shown to your customer |
|---|---|---|---|
| Add-on features, while the add-on is granted | Merged into features[] |
Merged into ActivatedFeatures[] |
Merged into the plan’s values |
An add-on’s name and description stay in the portal, and so does everything about a suite: its code, name, description and members.
A meter is copied onto an entitlement when its product is attached. A later change to its name, unit, number format or tiers doesn’t reach entitlements that already exist; a change to its period does.
| Field | Signed license | Sent to your application | Shown to your customer |
|---|---|---|---|
| Metric name | The key in usage_limits |
Meters[].MetricName |
Yes |
| Maximum usage, the highest tier end | usage_limits |
No | The current tier’s limit |
| Display name | No | No | Yes |
| Unit | No | Meters[].Unit |
Yes |
| Number format | No | No | Yes |
| Period | No | No | Yes |
| Asset balance: display name, unit, number format and credits | No | No | Yes |
A meter’s description, category and value type stay in the portal. A meter that only a left-out
feature reads, one that is Not included or whose catalog entry is Draft, Disabled or Archived, is left
out of Meters too.
Claims in every license
Section titled “Claims in every license”Every signed license carries iss, aud, key_id, rev, jti, dev_fp, sub, iat,
nbf, exp, lease, lease_exp, trial_exp, grace_exp, lic, features,
products and usage_limits. None of them can be left out. sub is empty when nobody signed in, and a
metric is in usage_limits only when it has a maximum. Two more appear only in special
cases: try on a try license, and evaluation while your own Oclavex account is
evaluating.
What this means for your application
Section titled “What this means for your application”- Leaving a feature out is all or nothing. A setting keeps a whole feature out of the signed license; it can’t keep one of its fields out.
- Enforce on the signed license. Read features and limits through the SDK’s validation, which uses the signed claims. Use the unsigned fields for what you show.
- Dates are checked on the device. The SDK compares
nbf,expand each feature’sexpwith the device’s clock at every check. A feature stops when its ownexppasses, even on a license issued earlier and on a device that is offline. A license whosenbfis more than five minutes ahead reportsNotYetValid. - Treat everything that reaches the device as readable. That includes unsigned feature values and Public product properties.
For reading these values in .NET, see .NET SDK — enforce entitlements.