Entitlement Groups

Named sets of entitlements — how to create a group, add and remove members, and read the aggregated usage of a group for one instance.

What a group is

An entitlement group collects related entitlements under one label. It is a lightweight container: membership changes nothing about how an entitlement is measured, granted, or enforced — it gives the catalog a structure the console and your customer-facing components can display, and one read that returns the usage of every member for an instance. Kaiten Sushi Shop defines two:

Group "Delivery" (delivery)
├── delivery-drivers   NUMBER · LATEST
└── delivery-tracking  BOOLEAN

Group "Restaurant Operations" (restaurant-operations)
├── menu-items         NUMBER · LATEST
├── monthly-orders     NUMBER · SUM · monthly
├── locations          NUMBER · LATEST
└── support-tier       CONFIG

Every seeded entitlement belongs to exactly one of the two; neither group carries a description.

An entitlement can belong to several groups, and a group can mix types. Every entitlement response lists its groups under entitlementGroups.

Examples use $KAITEN_API and $KAITEN_TOKEN as set up in the quickstart, and add a group next to the seeded ones. Group routes take read:entitlements / write:entitlements.

Create a group

A group has no page of its own in the console: it is created from the group picker — the Groups field of the entitlement form, or the Groups cell of the Entitlements table. Type a name that matches no existing group — Kitchen — and choose Create "Kitchen": the group is created and assigned in one step.

The console sets the name only: the slug is derived from it, with a random suffix, and the description stays empty. To choose the slug, create the group over the API; a description can be added afterwards with PUT. Renaming and deleting a group are API calls too.

curl -X POST "$KAITEN_API/entitlement-groups" \
  -H "Authorization: Bearer $KAITEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kitchen",
    "slug": "kitchen",
    "description": "Everything the kitchen staff depends on."
  }'

{
  "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "name": "Kitchen",
  "slug": "kitchen",
  "description": "Everything the kitchen staff depends on."
}

201 Created, and ENTITLEMENT_GROUP_CREATED is emitted.

Property	Type	Required	Description
`name`	`string`	Yes	Display name — Kitchen
`description`	`string`	Yes	What the group collects
`slug`	`string`	No	2–100 characters, `^[a-z0-9][a-z0-9-]*[a-z0-9]$`, unique per organization; derived from the name with a random suffix when omitted

PUT /entitlement-groups/{slug} replaces the name and description (204 No Content, ENTITLEMENT_GROUP_UPDATED). DELETE /entitlement-groups/{slug} removes the group and its memberships — never the member entitlements (204, ENTITLEMENT_GROUP_DELETED).

Add and remove members

At creation of an entitlement

Pass groupSlugs when creating the entitlement:

curl -X POST "$KAITEN_API/entitlements" \
  -H "Authorization: Bearer $KAITEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kitchen Screens",
    "slug": "kitchen-screens",
    "description": "Kitchen display screens a restaurant can connect.",
    "type": "NUMBER",
    "aggregationMethod": "LATEST",
    "groupSlugs": ["kitchen", "restaurant-operations"]
  }'

After creation

Add an existing entitlement to a group — 201 Created:

curl -i -X POST "$KAITEN_API/entitlement-groups/kitchen/entitlements" \
  -H "Authorization: Bearer $KAITEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "entitlementSlug": "menu-items" }'

Remove it — 204 No Content:

curl -i -X DELETE "$KAITEN_API/entitlement-groups/kitchen/entitlements/menu-items" \
  -H "Authorization: Bearer $KAITEN_TOKEN"

Removing an entitlement from a group, or deleting the group, never touches the entitlement, its grants, or its usage records. Membership is a label.

Read a group's usage

One call returns the usage of every member for one instance, each next to the value the instance's License grants:

curl "$KAITEN_API/entitlement-groups/delivery/usage?instance=sakura-tokyo-prod" \
  -H "Authorization: Bearer $KAITEN_TOKEN"

[
  {
    "entitlementId": "4e5f6a7b-8c9d-4e0f-1a2b-3c4d5e6f7a8b",
    "entitlementSlug": "delivery-drivers",
    "entitlementName": "Delivery Drivers",
    "entitlementType": "NUMBER",
    "usageValue": { "type": "number", "value": 8, "event_count": 5 },
    "licenseValue": { "type": "number", "value": 10 }
  },
  {
    "entitlementId": "5f6a7b8c-9d0e-4f1a-2b3c-4d5e6f7a8b9c",
    "entitlementSlug": "delivery-tracking",
    "entitlementName": "Delivery Tracking",
    "entitlementType": "BOOLEAN",
    "licenseValue": { "type": "boolean", "value": true }
  }
]

Field	Meaning
`usageValue`	The member's usage record for the instance — omitted when nothing has been reported yet, and for `BOOLEAN` / `CONFIG` members, which are never metered
`licenseValue`	The value the instance's License grants — omitted when the License grants nothing for this member
`currentPeriodStart` / `currentPeriodEnd`	The window a periodic counter's total belongs to; omitted for a lifetime counter

The instance query parameter is required. The response is the per-member view; the enforcement of each NUMBER member — its overage allowance — is read on the grant, not here (Usage & Thresholds).

API reference

Method	Endpoint	Description
`GET`	`/entitlement-groups`	List groups (cursor-paginated)
`POST`	`/entitlement-groups`	Create a group
`GET`	`/entitlement-groups/{slug}`	Get a group
`PUT`	`/entitlement-groups/{slug}`	Replace a group's name and description
`DELETE`	`/entitlement-groups/{slug}`	Delete a group; its members are untouched
`POST`	`/entitlement-groups/{slug}/entitlements`	Add an entitlement to a group
`DELETE`	`/entitlement-groups/{slug}/entitlements/{entitlementSlug}`	Remove an entitlement from a group
`GET`	`/entitlement-groups/{slug}/usage?instance={instanceSlug}`	Aggregated usage of the members for one instance

Events

Event name	Event type
`ENTITLEMENT_GROUP_CREATED`	`com.kaiten.entitlement_group.v1.created`
`ENTITLEMENT_GROUP_UPDATED`	`com.kaiten.entitlement_group.v1.updated`
`ENTITLEMENT_GROUP_DELETED`	`com.kaiten.entitlement_group.v1.deleted`

Exact reference — the group and membership tables: the data model.

On this page