---
repo: tenant-engine
updated: "2026-07-23"
---

# INTENT

## Purpose

`tenant-engine` exists to be the single, canonical source of truth for what a
**tenant** is on the NetKingdom platform — its existence, its onboarding
grouping, its capability roles, and its plan/subscription assignment —
separate from who its *users* are (`user-engine`), who *authenticates* it
(`key-cape`/Keycloak), who *authorizes* actions against it (`flex-auth`), and
what it *pays* for a given plan (`adaptive-pricing`).

Full ownership boundary, formally: `net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md`.

## Why This Exists

No service in the fleet currently owns tenant-as-an-entity facts as a
queryable resource. `user-engine`'s own boundary contract explicitly scopes
it to *consuming* tenant identifiers and *storing records scoped by* a
tenant — not owning the tenant record itself. The IAM Profile defines the
*shape* of the `tenant` claim, not a live directory of which tenants exist,
what they're allowed to do, or what plan they're on.

That gap became concrete during Binky Hedgehog GmbH's onboarding as the
platform's first tenant outside `tenant:coulomb`
(`key-cape/workplans/KEY-WP-0004-binky-hedgehog-tenant-onboarding.md`): a
tenant's **capability roles** (`PLTF`/`IAM`/`VEN`/`CUS`, non-exclusive — a
tenant can hold several at once, and its roles can change independently of
how it was onboarded) needed a real owner, a real carrying mechanism, and a
real governance model (role grants are usually a consequence of a paid
plan). See `net-kingdom/docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md`
and `ADR-0014-tenant-capability-roles-and-tenant-engine-ownership.md`.

## Primary Utility

`tenant-engine` provides:

- **Tenant records**: existence, identifier, and onboarding grouping
  (`trial`/`friendly`/`single`/`small`/`medium`/`large`/`enterprise`/
  `consumer`/`family`/`community`/`association`/`agentic`, per ADR-0013).
- **Capability role grants**: `PLTF`/`IAM`/`VEN`/`CUS`, with an audited
  grant/revoke trail linking most grants to a plan-assignment change.
- **Plan/subscription assignment**: which `adaptive-pricing` plan a tenant
  currently holds, referenced by id — never a duplicated copy of plan terms.
- **A cache-read API** `key-cape` calls at token-issuance time to source the
  optional `tenant_roles` token claim (IAM Profile v0.3).
- **A live-lookup API** `flex-auth` calls synchronously for privileged,
  high-stakes decisions — the case where a cached claim isn't trustworthy
  enough (a stale `VEN` grant surviving a plan cancellation is not an
  acceptable risk for money-movement or credential-vending actions).
- Reserved, not yet implemented: **guardrail/quota policy** (spend limits,
  entity/action counts) — `trial`-grouped tenants default to a **zero**
  spend budget; design is future work.

## Intended Users

- `key-cape` / Keycloak, at token issuance time (cache-read API).
- `flex-auth`, at authorization-decision time (live-lookup API, and the
  target of write-authorization for grant/revoke/plan mutations).
- Operators and tenant administrators, indirectly, through whatever admin
  surface eventually consumes `tenant-engine`'s APIs (not yet built).
- `adaptive-pricing`, as the source `tenant-engine` references for plan
  *definitions* (not the other way around).

## Strategic Role

`tenant-engine` sits **beside** `user-engine`, not inside it — a deliberate
bounded-context split, not an oversight. `user-engine`'s aggregate root is
the *person*; `tenant-engine`'s is the *tenant*. Consumers that only need a
fast, security-critical tenant-role lookup (`flex-auth` on every privileged
decision, `key-cape` on every token issuance) should never need to depend on
`user-engine`'s much larger surface (registration flows, factor models,
family dataspace onboarding) to get it. This matches the fleet's existing
convention of many small, single-purpose `-engine`/`-core` services rather
than one large one.

## Responsibility Boundary

`tenant-engine` owns tenant-as-an-entity facts. It never re-derives or
duplicates facts another system already owns.

### tenant-engine Owns

- Tenant existence, identifier, and onboarding grouping.
- Capability role grants and their audit trail.
- Plan/subscription assignment (by reference, not by copying plan terms).
- Reserved: guardrail/quota policy, once designed.

### Other Systems Own

| Concern | Owner |
| --- | --- |
| OIDC discovery, login, token issuance | `key-cape`, Keycloak |
| Tenant identifier format and role vocabulary | NetKingdom (IAM Profile, ADR-0013, ADR-0014) |
| Users, profiles, memberships | `user-engine` |
| Authorization decisions | `flex-auth` |
| Pricing-model / plan definitions | `adaptive-pricing` |
| Runtime secrets | OpenBao / `secrets-engine` |
| Payment processing | Not yet identified — `tenant-engine` records plan assignment, not payment execution |

## Non-Goals

- Not an identity provider. Never issues, verifies, or refreshes tokens.
- Not a policy decision point. Never makes an authorization decision itself
  — it answers queries `flex-auth` issues.
- Not a billing processor. Records plan assignment, not payment execution.
- Not a pricing-model engine. References `adaptive-pricing` plan ids.
- Not the user/membership domain. Never stores user accounts or profiles.

## Governing Principle

This repository should stay focused on the purpose above. Work that changes
its authority, ownership boundaries, or operational promises should be
captured in a workplan before implementation, and should stay consistent
with `net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md` —
if the two drift, the canon contract wins and this file should be corrected.

## Related

- `docs/flex-auth-integration.md` — how the write API's `WriteAuthorizer`
  seam is implemented against a real `flex-auth`
- `net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md` — the
  formal ownership contract
- `net-kingdom/canon/standards/iam-profile_v0.3.md` — the `tenant_roles`
  claim and carrying mechanism this service implements
- `net-kingdom/docs/adr/ADR-0013-tenant-onboarding-grouping-taxonomy.md`
- `net-kingdom/docs/adr/ADR-0014-tenant-capability-roles-and-tenant-engine-ownership.md`
- `key-cape/workplans/KEY-WP-0004-binky-hedgehog-tenant-onboarding.md` — the
  first tenant this service will record