Quickstart

Set up your environment

export KAITEN_API="https://app.kaiten.sh/api"

git clone https://github.com/kaitencloud/kaiten.git
cd kaiten
cp .env.example .env   # the defaults work locally
task dev               # the backend, its accounts, the Kaiten Sushi Shop dataset, and the console

export KAITEN_API="http://localhost:6060/api"

The demo sandbox and the demo seed profile load the same dataset: the Kaiten Sushi Shop, a restaurant-software vendor with four customers on three License families, entitlements with usage, and flags that read them. The console tour walks through it; this quickstart builds its own entities next to it.

Model a customer and their contract

You build the model from the offer outward: first what you sell — an Entitlement granted by a License — then who buys it — a Customer — then where it runs for them — an Instance under that License. The cast: you are Kaiten Sushi Shop, a restaurant-software vendor, signing the restaurant Sakura Kyoto.

The Entitlement

A NUMBER entitlement is a metered quota. This one counts priority orders, sums each report, and resets monthly. How strictly the quota is enforced is not decided here — it is written on each License's grant, in the next step.

1. Open Entitlements and click New Entitlement.
2. Name: Priority Orders · Slug: priority-orders · Description: Priority orders a restaurant can place per month. Click Next.
3. On the Type configuration step — Type: Number · Aggregation Method: Sum · Usage resets: Every month · Window aligned on: Calendar. Click Create Entitlement.

The License, granting 5 priority orders a month

1. Open Licenses and click New License: Name Omakase, Type Paid, Description The top tier — everything on the menu.
2. Under Entitlements & limits, on the same page, click Add entitlement: Entitlement Priority Orders, Threshold / limit 5, Overage allowance (%) 0 — a hard cap: a report that would take the total past 5 is refused.
3. Click Create License. The License is published unless Save as draft is ticked.

The second action writes the contract side — how much this tier grants, and how strictly. The chain so far: Omakase → 5 priority orders / month, hard cap.

✕

✕

The Customer

1. Open Customers and create a new customer.
2. Name: Sakura Kyoto — the slug auto-generates to sakura-kyoto.

The Instance

The Instance ties it together: the production copy of your product running for Sakura Kyoto, under the Omakase License.

1. Open the Sakura Kyoto customer and, in its Instances card, click New Instance.
2. Name: Sakura Kyoto Production — slug sakura-kyoto-production — Description: Production instance for Sakura Kyoto. Click Next.
3. On Choose the license — License: Omakase v1; the License Date range defaults to one year from today. Click Next.
4. Leave Deployment empty — and Metadata, a step that appears where the organization declares metadata fields for instances — and click Create Instance.

The chain is complete: Sakura Kyoto → sakura-kyoto-production → Omakase → 5 priority orders / month.

Create a service account and token

Everything from here on is your product talking to Kaiten — and programmatic access goes through a service account, a machine identity in your organization, holding API tokens (ksh_...) with explicit scopes.

1. Open Integrations → Service Accounts, click Create Service Account, and name it quickstart.
2. On the service account, click Generate Token. On the New Token page, name the token local-dev and, under Access, set Customers, Instances, Licenses, Entitlements and Feature Flags to Read & write — on a short screen, Adjust per resource opens that table. The summary lists the scopes the token will carry: the five write: scopes this guide needs, each with its read:.
3. Click Create Token, then Copy token. The token is shown once, on that page: Kaiten keeps only a hash of it.

export KAITEN_TOKEN="ksh_..."

✕

✕

Enforce the limit

Reporting usage is an API act by nature — in production your product's backend reports, through one of the Kaiten SDKs — the Go client, the Python client, or @kaitencloud/server — or plain HTTP as below. Report 4 priority orders:

curl -X POST "$KAITEN_API/instances/sakura-kyoto-production/entitlements/priority-orders/usage" \
  -H "Authorization: Bearer $KAITEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": {"type": "number", "value": 4}, "behavior": "append"}'

{
  "entitlementId": "a1e2d3c4-b5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "entitlementSlug": "priority-orders",
  "licenseId": "b2f3e4d5-c6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "licenseSlug": "omakase",
  "value": {"type": "number", "value": 4, "event_count": 1},
  "limit": {"type": "number", "value": 5},
  "currentPeriodStart": "2026-09-01T00:00:00Z",
  "currentPeriodEnd": "2026-10-01T00:00:00Z"
}

value is the observed side, limit the contract side, and the period bounds show the monthly window this counter lives in. Now open Customers → Instances, then Sakura Kyoto Production, then its Entitlements & Usage tab: Priority Orders reads the same 4 / 5 — the console and the API read one record.

✕

✕

One order remains. Try to report three more — 4 + 3 would exceed the granted 5, and the Omakase grant is a hard cap with no allowance past it:

curl -i -X POST "$KAITEN_API/instances/sakura-kyoto-production/entitlements/priority-orders/usage" \
  -H "Authorization: Bearer $KAITEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": {"type": "number", "value": 3}, "behavior": "append"}'

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.8",
  "title": "Conflict",
  "status": 409,
  "code": "ReportEntitlementUsageMetric.ThresholdExceeded",
  "detail": "Usage for priority-orders exceeds the allowed threshold",
  "instance": "/api/instances/sakura-kyoto-production/entitlements/priority-orders/usage"
}

The report is refused and not written — the stored total is still 4. That refusal is itself recorded: an ENTITLEMENT_USAGE_REPORT_REJECTED event lands in the audit trail, so the pushback is as auditable as the acceptance. Had the grant carried a 50 % allowance instead of 0, the maximum allowed usage would have been 7.5 and the same report would have been accepted at 7 — the allowance, like the value, is the grant's decision.

Evaluate a flag that reads the contract

Feature flags in Kaiten evaluate through OFREP (the OpenFeature Remote Evaluation Protocol) with CEL targeting rules — and a rule can read the instance's entitlements directly through the server-provided __kaiten facts. Create a flag that keeps the priority-ordering flow visible only while the quota has room:

1. Open Feature Flags and click New Feature Flag. On Basic Information — Name: Priority ordering · Slug: priority-ordering-enabled, typed after the name, which fills the slug in as you type · Type: Boolean. Leave the switch in the header on Enabled.
2. On Variants Configuration, a boolean flag starts with two variants named true and false, whose values are locked: rename them on and off. On Default Variant, keep Simple Variant and choose off.
3. On Targeting Rules, click Add First Rule: Targeting Type Basic Targeting, Name Priority orders left, Variant on, and the CEL Expression below. Click Save, then Create Feature Flag.

__kaiten.entitlements["priority-orders"].remaining > 0.0

✕

✕

Evaluation is the API call your product makes on every check. Evaluate the flag for the instance:

curl -X POST "$KAITEN_API/ofrep/v1/evaluate/flags/priority-ordering-enabled" \
  -H "Authorization: Bearer $KAITEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"context": {"targetingKey": "sakura-kyoto", "kaiten": {"instanceSlug": "sakura-kyoto-production"}}}'

{
  "key": "priority-ordering-enabled",
  "value": true,
  "variant": "on",
  "reason": "TARGETING_MATCH"
}

Usage is 4 of 5, so remaining is 1.0, the rule matches, the flag is on. Now consume the last order:

curl -X POST "$KAITEN_API/instances/sakura-kyoto-production/entitlements/priority-orders/usage" \
  -H "Authorization: Bearer $KAITEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": {"type": "number", "value": 1}, "behavior": "append"}'

The total reaches the cap exactly — accepted, and Kaiten emits INSTANCE_ENTITLEMENT_USAGE_REACHED, the event you would wire to an alert or an upsell flow. Evaluate the flag again, same call, no deploy, no config change:

{
  "key": "priority-ordering-enabled",
  "value": false,
  "variant": "off",
  "reason": "DEFAULT"
}

remaining is 0.0, no rule matches, the default variant serves. The contract turned the feature off. Commercial state and runtime behavior are one system here, so they cannot drift apart.

Where to go next

You modeled what a customer bought and what they can use. Kaiten also records what runs for them — your components, the releases you cut, and the deployment zones each Instance runs in: that is Deployments. And when your product calls Kaiten from its code rather than with curl, the SDKs wrap the same API.