Entitlements

What an entitlement is

An entitlement is one typed right in your catalog — a quota, a switch, or a structured setting — defined once and granted at a value by each License. The catalog says what can be granted and how it is measured; the grant says how much a License gives and how strictly that number is enforced; the usage record says how much an instance has consumed. Kaiten Sushi Shop's monthly-orders, read across its three Licenses:

Entitlement "Monthly Orders" (monthly-orders)
├── Type: NUMBER · aggregation: SUM
├── Warning threshold: none (0 — the early warning is off)
├── Reset period: MONTH, anchored on the calendar
└── Granted by
    ├── Starter  → 20    · overage allowance 0 %   (hard cap)
    ├── Standard → 100   · overage allowance 10 %  (accepted up to 110)
    └── Premium  → 1,000 · overage allowance 20 %  (accepted up to 1,200)

Each License here is a family of versions, and a grant belongs to one version; every version of these three grants monthly-orders the same value.

Read the tree from the top and you have the measurement, identical for every License. Read the three grants and you have the contract: the same entitlement is a hard cap on one License and a soft limit with a bounded allowance on another, because enforcement is written on the grant.

The four types

How it works

1. Define the catalog — POST /entitlements, one per right. A NUMBER carries its aggregation method, an optional warning threshold, and an optional reset period; a BOOLEAN or CONFIG carries none of these.
2. Grant per License — POST /licenses/{slug}/entitlements with the typed value and, for a NUMBER, limitCapExceededOveragePercent: -1 unlimited, 0 hard cap, > 0 the tolerated overage. One grant per License–entitlement pair.
3. Attach instances to a License — every instance resolves its entitlements through the grants of its License, from its next read or report.
4. Report usage — your product posts each NUMBER consumption to POST /instances/{slug}/entitlements/{slug}/usage; Kaiten folds it into the stored total and compares the result with the grant's maximum allowed usage. Above it, the report is refused with 409 and nothing is written.
5. React — the threshold crossings, the accepted and refused reports, and every closed usage window are events, delivered as webhooks on Kaiten Cloud Kaiten Cloud or consumed from RabbitMQ when self-hosted, and recorded in the instance's audit trail.

In this section

API endpoints overview

Scopes follow the module: read:entitlements / write:entitlements for the catalog and the groups, read:licenses / write:licenses for the grants, read:instances / write:instances for usage. See scopes.

Catalog

Deleting an entitlement deletes its usage: a counter measures nothing once its entitlement is gone. A grant is different — it is a commercial decision recorded on a License, so an entitlement a License still grants is refused with 409 Conflict (DeleteEntitlement.InUseConflict). Remove the grants first, with DELETE /licenses/{slug}/entitlements/{entitlementSlug}.

Grants

Groups

Usage

Events

The event catalog lists every event with its payload; events and webhooks explains the two delivery paths.

Where to go next

The one-screen versions: Licenses & Entitlements for the contract side, Usage & Metering for the observed side. Exact reference — tables, columns, constraints: the contract section of the data model.