--- id: NK-ADR-0013 type: architecture-decision-record title: "Tenant Onboarding Grouping Taxonomy" status: accepted owner: net-kingdom revision: "2" decided: "2026-07-23" last_reviewed: "2026-08-22" review_interval: 12m --- # ADR-0013 - Tenant Onboarding Grouping Taxonomy **Status:** Accepted **Date:** 2026-07-23 **Amended:** 2026-08-22 (current classification versus historical identifier segment) **Deciders:** Bernd Worsch, Codex ## Context `canon/standards/iam-profile_v0.2.md`'s "Tenant Claim" section lists four *suggested* (not exhaustive) tenant identifiers: `tenant:platform`, `tenant:coulomb`, `tenant:sandbox:`, `tenant:customer:`. Separately, an unratified exploration (`docs/princedom-isolation-exploration.md`) proposes a non-exclusive **capability-role** model for tenants: `PLTF` (operates the platform), `IAM` (organizes its own users/secrets), `VEN` (provides apps/services to others), `CUS` (consumes apps/services from `PLTF` or `VEN` tenants) — one tenant can hold multiple roles simultaneously. Binky Hedgehog GmbH is being onboarded as the platform's first tenant outside `tenant:coulomb` (`key-cape/workplans/KEY-WP-0004-binky-hedgehog-tenant-onboarding.md`), forcing a concrete identifier decision. Binky already exercises both `CUS` (consumes `qonto-assistant`) and, per `binky-control/INTENT.md`, will exercise `VEN` (packages and sells offers built on the ecosystem to real external customers) — it is not purely a "customer" in the role sense. Using a capability-role word (`customer`, `vendor`, ...) as the tenant *grouping* segment collides with that separate role dimension: a tenant labeled `tenant:customer:binky` would carry a stale, misleading label the moment it also starts acting as a vendor, and tenant identifiers are expensive to rename once tokens, OpenBao paths, and downstream config reference them. ## Decision Adopt an onboarding-risk / entity-shape **grouping** taxonomy for the tenant identifier's second segment, replacing the `sandbox`/`customer` suggested identifiers in `iam-profile_v0.2.md`'s "Tenant Claim" section: ```text tenant:: trial - test/trial/showcase tenants only friendly - known, easily reached, tolerant of experimentation/instability single - one-person business entities (freelance consultants) small - up to 10 employees at time of onboarding (attoo) medium - up to 100 employees (attoo) large - up to 1000 employees (attoo) enterprise - 1001+ employees (attoo) consumer - private individuals family - a legal family community - a non-legal group of people association - a legal association of people agentic - financially enabled AI entities ``` The taxonomy has two deliberately different uses: - At creation, the identifier's grouping segment records the tenant's onboarding-time classification. The complete identifier is immutable, so this segment is historical after creation. - The tenant record's `grouping` field records current classification. It may change as the entity changes and is authoritative for present-day policy, including guardrails and spend ceilings. No consumer may parse the identifier's middle segment and treat it as current grouping. Consumers needing current grouping MUST read it from `tenant-engine`. Identifier creation still validates the segment against this vocabulary; historical does not mean free-form or optional. Grouping is deliberately **orthogonal to capability role** (`PLTF`/`IAM`/`VEN`/`CUS`, subsequently ratified by ADR-0014): grouping describes *what kind of entity a tenant is and its current onboarding-risk classification*; role describes *what it does on the platform*. Both are carried as tenant metadata, but never conflated into the immutable identifier segment — that conflation is exactly what this ADR avoids. `tenant:platform` and `tenant:coulomb` remain **reserved, ungrouped identifiers outside this taxonomy**: `tenant:platform` is the control-plane root, not a business entity being onboarded; `tenant:coulomb` is the reference tenant established by ADR-0006, predating this taxonomy, and none of the twelve groupings meaningfully describe "the platform building itself." The taxonomy applies to tenants onboarded from here forward. *(This sub-point completes an open question raised during KEY-WP-0004 drafting and is Codex's reasoned proposal — flagged for Bernd's explicit confirmation rather than assumed settled.)* First application: Binky Hedgehog GmbH maps to `friendly` — known, reachable, tolerant of early instability — giving **`tenant:friendly:binky`** (`key-cape/workplans/KEY-WP-0004-binky-hedgehog-tenant-onboarding.md`). ## Scope and Governance Classification Per ADR-0011's breaking-change governance, this does **not** meet the breaking-change bar: it doesn't add, remove, or rename a required claim; it doesn't change `tenant`'s type or validation rule (still an opaque string); it doesn't affect acceptance of any previously-issued token (`tenant:platform`, `tenant:coulomb` tokens remain valid as-is, and no `tenant:customer:*` or `tenant:sandbox:*` tokens have been issued yet). It only replaces non-normative suggested-identifier guidance for tenants onboarded going forward. Per ADR-0011's own versioning rule ("New versions are added as new files... except for clearly editorial fixes that do not affect semantics"), this qualifies as an **editorial update** to `iam-profile_v0.2.md`'s Tenant Claim section — not a new versioned profile document. ## Consequences - `canon/standards/iam-profile_v0.2.md`'s "Tenant Claim" section needs a follow-up edit replacing the `sandbox`/`customer` suggested identifiers with this taxonomy. Not made by this ADR itself — tracked as follow-up so the change is reviewable on its own. - `key-cape/workplans/KEY-WP-0004-binky-hedgehog-tenant-onboarding.md` already reflects this decision (`tenant:friendly:binky`). - Future tenant onboarding work should classify a tenant against this list before minting an identifier, rather than reaching for a role word. - Tenant identifiers never change when current grouping changes. The middle segment is creation-time history; `tenant-engine` is authoritative for the current grouping value. - Policy and commercial consumers, including spend-ceiling resolution, MUST query `tenant-engine` and MUST NOT derive current grouping by splitting a tenant identifier. - The capability-role model (`PLTF`/`IAM`/`VEN`/`CUS`) remains a separate dimension, now ratified by ADR-0014. Role metadata is carried alongside — not instead of — current grouping and the historical identifier segment. - `tenant:platform` and `tenant:coulomb` are reserved outside the taxonomy, pending Bernd's explicit confirmation (see Decision). ## Alternatives Considered ### Keep using capability-role words as the tenant grouping Rejected: tenants are already known to hold multiple roles at once (Binky is `CUS` now, `VEN` later); a role-word grouping would need renaming as a tenant's roles evolve, which tenant identifiers are specifically expensive to do once tokens, OpenBao paths, and config reference them. ### Retrofit `tenant:coulomb` into the new taxonomy Considered `tenant:friendly:coulomb` or similar. Rejected for now: Coulomb is structurally the reference tenant from ADR-0006, predating this taxonomy, and none of the twelve entity-shape groupings describe "the platform's own ecosystem-development tenant." Revisit if a future grouping is ever added that genuinely fits it. ### Do nothing / keep the four original suggested identifiers Rejected: `tenant:customer:binky` was the working default going into Binky's onboarding despite the role-collision problem above; the fleet needs this resolved before the first non-Coulomb tenant goes live, not after. ## Follow-Up - Edit `canon/standards/iam-profile_v0.2.md`'s Tenant Claim section to replace the old suggested identifiers with this taxonomy (separate, reviewable change). - Confirm the `tenant:platform`/`tenant:coulomb` reserved/ungrouped treatment explicitly. - ADR-0014 and the Tenant Engine Boundary Contract define how capability-role metadata is carried alongside grouping. - Keep `tenant-engine`'s identifier parser vocabulary-validating for creation and lookup compatibility, but do not expose parsed grouping as current classification.