Core Concepts
Vocabulary
The canonical glossary — what each Kaiten term means, what it deliberately doesn't, and how it maps to the tools you already know.
Kaiten's data model only works because its words are precise. When a team says "plan" to mean three different things — the Stripe product, the flag segment, the row in the internal database — the glue code is already being written. So Kaiten is opinionated about vocabulary, and these docs, the console, and the API use these terms consistently. This page is the authority.
For each term: what it is, what it deliberately is not, and the name you might know it by in other tools — so you can translate your mental model instead of rebuilding it.
The model today
Every term in this table is backed by the API surface you can call right now.
| Term | What it is | What it is NOT | In other tools |
|---|---|---|---|
| Organization | You, the vendor — the company running Kaiten. The root of everything. | A customer's company; a workspace per team. | "Account" (Stripe), "Workspace" |
| Customer | A company you sell to. The commercial counterparty. | An end user; an infrastructure boundary; a billing object. | "Tenant", "Account", "Company" (CRMs) |
| Instance | One running copy of your product for one Customer. The bridge between contract and runtime. | The act of deploying; a server; an environment label. | "Deployment", "Environment" (infra sense) |
| Deployment zone | A logical execution environment where instances run — shared or dedicated. | The act of deploying; a Kubernetes cluster; a cloud region by itself. | "Environment" (flag tools), "Cluster" / "Region" (infra) |
| License | What a Customer bought — one version of a product, granting entitlements, attached to Instances. | A legal document; a price; a Stripe subscription. | "Plan" (billing tools), "Package" (Stigg) |
| License family | The product a License is a version of. It has a slug and no name of its own, and it serves one of its versions: its default, or else its newest published one. | One of its versions; a display name — two families may share one; a group of customers. | "Product" (billing catalogs) |
| Entitlement | A typed, checkable right granted by a License: BOOLEAN, NUMBER, CONFIG, or NUMBER_AI_CREDIT. | A feature flag; a permission/RBAC role; a usage counter by itself. | "Feature" (Stigg), "Limit", "Capability" |
| FeatureFlag | An OpenFeature-compatible flag with CEL rules — which can read entitlements directly. | The commercial right itself; an A/B testing framework. | "Flag" (LaunchDarkly, Unleash) |
| BYO-ID | Your own identifier carried on Kaiten records — a CRM record ID, a billing ID — so Kaiten matches your other systems without a mapping table. | A mapping table; a sync system. | "External ID" (Salesforce) |
| Audit trail | The immutable record of changes and evaluations, per organization and per instance. | An application log; an analytics event stream. | "Audit log" — but including evaluations |
Arriving with billing
Coming soonThree terms appear across Kaiten's roadmap material but have no API surface today. They are listed here so the vocabulary is complete — not because you can create one. They arrive with the commercial layer described in What's coming.
| Term | What it will be | In other tools |
|---|---|---|
| LicensePrice | What a License costs. One License composes several: a base fee plus usage meters. | "Price" (Stripe) |
| Addon | A stackable extension to a License, with explicit override behavior. | "Add-on" (billing tools) |
| Voucher | A redeemable code acting on more than one dimension at once: price, entitlement, flag. | "Coupon", "Promo code" — but more |
The choices behind the contested words
Four of these terms replace words you probably use today. The replacements are deliberate, and the reasoning matters more than the naming.
License, not Plan
"Plan" is the most overloaded word in SaaS — it means a Stripe product, a marketing tier, a row in your pricing table, and a vague intention. A License is none of those: it's the modeled object that grants entitlements — one version of a product, grouped with the product's other versions in a License family. The word carries the right intuition — something issued, attached, revocable, auditable. When sales says "Sakura Tokyo is on Premium," in Kaiten that's a verifiable fact about an attached License, not a label in a CRM field.
Customer, not Tenant or Account
"Tenant" is infrastructure vocabulary — it describes how you isolate data, not who pays you. "Account" is ambiguous (a user account? a bank account? a CRM account?). Customer says exactly what it is: the commercial counterparty. The infrastructure side of that relationship has its own word — the Instance.
Instance, not Deployment
"Deployment" is an event (the act of shipping) and a unit of infrastructure (a K8s Deployment). An Instance is neither — it's the durable object linking a Customer to a running copy of your product, the thing a License attaches to. One Customer, several Instances (production EU, sandbox), each with its own commercial reality. Kaiten does keep "deployment" for two precise things: the Deployment zone an instance runs in, and the Deployment journal entry that records a release landing in a zone.
Entitlement, not Feature
Tools that merged "feature" and "entitlement" into one concept forced a bad trade: either your commercial rights live in your flag tool (which doesn't know contracts) or your flags live in your billing tool (which can't target). Kaiten keeps them distinct — the Entitlement is the commercial right, the FeatureFlag is the runtime decision — and lets the flag read the entitlement. The separation is what keeps the unified model composable.
Supporting vocabulary
The operational terms you'll meet in the API and the console, one line each.
| Term | Meaning |
|---|---|
| Slug | URL-safe identifier, unique per organization, used in API paths (/customers/{customerSlug}). |
| License version | One License of a License family, numbered by the server and never renumbered. A version is a draft, published, or archived; an Instance is pinned to one version. |
| Default version | The version a License family puts forward — at most one per family, always a published one. There is no default License for the organization as a whole. |
| LicenseEntitlement | The join between a License and an Entitlement — it stores the granted value (the contract side). |
| EntitlementUsage | The current consumption of one entitlement on one instance (the observed side). |
| Entitlement group | A named set of entitlements, with an aggregated usage view. |
| Variant | A value a feature flag can resolve to (on/off, or multi-variant payloads). |
| Targeting rule | A CEL expression that selects a variant when a flag is evaluated; first match wins, otherwise the default variant. |
| CEL | Common Expression Language — the expression language of targeting rules. |
| OpenFeature | The open flag-management standard Kaiten implements as a provider. |
| OFREP | OpenFeature Remote Evaluation Protocol — POST /ofrep/v1/evaluate/flags/{key} (single) and POST /ofrep/v1/evaluate/flags (bulk). |
| Component | A versioned building block of your product (e.g. api v2.3.1). |
| Release | A versioned bundle of components — the shippable unit. |
| Deployment | The journal entry recording that a release was deployed to a deployment zone. |
| Metadata field | An admin-declared typed property on Instances or Deployment zones, validated by JSON Schema. |
| Domain event | A structured notification emitted on change or evaluation (e.g. com.kaiten.customer.v1.created). |
| Webhook | A managed endpoint receiving domain events on Kaiten Cloud; self-hosted installations consume the event stream directly. |
| Service account | A machine identity in your organization, used for programmatic access. |
| API token | A ksh_-prefixed credential issued to a service account, carrying scopes. |
| Scope | A permission string gating API operations: read:<module>, write:<module> (which implies read), and — on the Platform API only — delete:<module>. |
Naming conventions
Every slug is kebab-case — lowercase letters, digits, and hyphens — and the API enforces it: a slug must match ^[a-z0-9][a-z0-9-]*[a-z0-9]$, so an underscore is refused. The docs and examples name things accordingly:
- Entitlements —
monthly-orders,delivery-tracking,menu-items. A rule indexes one with its slug as the key:__kaiten.entitlements['monthly-orders']. - Feature flags —
delivery-tracking-enabled,analytics-dashboard-enabled. A flag that gates what an entitlement grants can carry the entitlement's slug, suffixed.
Choose slugs carefully the first time — renaming one later means touching every call site.
Contributing to Kaiten? This vocabulary is enforced in code review. A PR that introduces "plan", "tenant", or "deployment" (as an entity) in docs, UI copy, or API naming will be asked to rename. The model's coherence is the product, and consistent naming is what keeps it.
Where to go next
Overview
The Kaiten model in one diagram — who you sell to, what they bought, where your product runs for them, and how flags, usage, and events hang off the same records.
Customers & Instances
The top of the hierarchy in practice — the company you sell to, and the running copy of your product that carries its contract.