Previewkernable is not released yet: these docs describe work in progress, and things may change before 1.0.Not released yet.Request early access →
Skip to content

Tenancy ​

A tenant is one customer organisation of your application: a company using your SaaS, a school, a shop. Everything that belongs to it (its identities, groups, invitations, and your own aggregates) lives under its tenant ID, so the kernel keeps tenants apart and can erase or move one as a whole.

The tenant ​

One aggregate, tenancy.tenant, whose ID is the tenant ID: a tenant acme lives under the tenant acme. It holds:

FieldWhat it is
sluga short name for URLs and subdomains (acme.example.com): 3–63 lowercase letters, digits and single dashes, unique across tenants, not one of RESERVED_SLUGS
namethe display name
statuspending, active, suspended or deleted
ownersthe identities that own it; at least one once the first owner joined
suspensionwhy it is suspended: owner_requested, unpaid, abuse, by_platform or rejected
mfaRequiredwhether everyone in it needs a second factor
signUpthe platform tenant only: the sign-up policy

Lifecycle ​

  • A suspended tenant keeps its data, but the middleware refuses its requests (tenant_suspended). The platform can still act on it; its owners can reactivate it only if they suspended it themselves (owner_requested).
  • Deleting is only possible from suspended, after DELETE_AFTER_DAYS (0 by default). It frees the slug, and the kit's reactors delete the tenant's identities and erase the emails of its invitations, both with their personal data; then every kit read model drops the tenant's rows. Your own read models should do the same on tenancy.TenantDeleted.
  • A rejected self-service tenant (rejected) cannot be reactivated.

The platform tenant ​

One tenant is special: the platform tenant (PLATFORM_TENANT, platform by default). It is where every account and every session lives, and where the people who run your application have their identities. Its groups hold their permissions in every tenant, and its owners hold every permission everywhere. It cannot be suspended or deleted. bootstrap() creates it.

Its tenant also holds the sign-up policy, changed with ChangeSignUpPolicy:

SettingValuesEffect
accountsoff, openopen: anyone may register. off: accounts come only from invitations
tenantsoff, pending, activewhether a signed-in person may create a tenant themselves, and whether it starts active or waits as pending for the platform's ActivateTenant

Owners ​

Owners are kept on the tenant itself, nowhere else. They hold every permission in their tenant and appear in group lists as the virtual group owners, which cannot be deleted. The last owner cannot be removed (last_owner).

How the first owner arrives depends on who creates the tenant:

  • Self-service: a signed-in person sends CreateTenant with owner: { accountId } (their own account). The kit creates their identity in the new tenant and adds it as owner.
  • By the platform: CreateTenant with owner: { email }. The kit sends an owner invitation to that address; accepting it adds the person as owner.

An identity that owns its tenant cannot be deleted; remove it as owner first. The kernel checks this atomically through the tenant's owner key.

Requiring a second factor ​

RequireMfa with required: true makes the middleware refuse every request in the tenant from a session without a second factor (mfa_required): TOTP or a recovery code proved in this session, or a passkey, which counts as two factors. API keys of service identities are not affected.

Settings ​

In kit/src/shared/constants.ts (Python: kit/shared/constants.py, Rust: src/shared/constants.rs):

ConstantDefaultWhat it does
PLATFORM_TENANTplatformthe platform tenant's ID
RESERVED_SLUGSplatform, www, api, admin, app, mail, auth, login, staticslugs nobody may take
DELETE_AFTER_DAYS0how long a suspended tenant waits before it may be deleted

Reference ​

Types ​

The types the tables below name, from tenancy/domain.ts:

ts
type TenantStatus = "none" | "pending" | "active" | "suspended" | "deleted";

type SuspensionReason = "owner_requested" | "unpaid" | "abuse" | "by_platform" | "rejected";

interface SignUpPolicy {
  /** The status a self-service tenant starts with, or `off`. */
  tenants: "off" | "pending" | "active";
  accounts: "off" | "open";
}

type Owner = { email: string } | { accountId: string };

Aggregates ​

AggregateUnique keysFacts
tenancy.tenantslug (global), owneractive, exists

Commands ​

Secret fields leave the vault once the command completes; personal fields stay in the vault until their subject is erased.

CommandFieldsWritesWho may send itRefused with
ActivateTenant
on tenant
—TenantActivatedthe platforminvalid_state
AddOwner
on tenant
identityId: stringOwnerAddedownersexists, invalid_identity, not_found; requires: identity.identity is active
ChangeSignUpPolicy
on tenant
tenants: "off" | "pending" | "active"
accounts: "off" | "open"
SignUpPolicyChangedthe platforminvalid_policy, not_found, platform
ChangeTenantSlug
on tenant
slug: stringTenantSlugChangeda group permissioninvalid_slug, invalid_state
CreateTenant
on tenant
slug: string
name: string
owner: Owner
status?: "active" | "pending"
TenantCreatedany signed-in account (self-service; the platform's groups otherwise)exists, invalid_name, invalid_owner, invalid_slug, invalid_tenant
DeleteTenant
on tenant
—TenantDeletedthe platforminvalid_state, platform, too_early
ReactivateTenant
on tenant
—TenantReactivatedthe platform (owners too, after owner_requested)invalid_state
RemoveOwner
on tenant
identityId: stringOwnerRemovedownerslast_owner, not_found
RenameTenant
on tenant
name: stringTenantRenameda group permissioninvalid_name, invalid_state
RequireMfa
on tenant
required: booleanMfaRequirementChangedownersinvalid_state
SuspendTenant
on tenant
reason: SuspensionReasonTenantSuspendedthe platform (owners too, with owner_requested)invalid_reason, invalid_state, platform

Events ​

EventFieldsVaultNote
TenantCreatedslug: string
name: string
owner: Owner
status: "active" | "pending"
——
TenantActivated———
TenantRenamedname: string——
TenantSlugChangedslug: string——
TenantSuspendedreason: SuspensionReason
at: number
——
TenantReactivated———
TenantDeleted———
OwnerAddedidentityId: string——
OwnerRemovedidentityId: string——
MfaRequirementChangedrequired: boolean——
SignUpPolicyChangedtenants: "off" | "pending" | "active"
accounts: "off" | "open"
——

Queries ​

A query about one aggregate names it (static target): the middleware decides on that aggregate as on a command's.

QueryFieldsAboutAnswerWho may ask
GetTenantBySlug
by tenancy.tenants
slug: string—{ id: string; name: string; status: TenantStatus }the API (its api group)
GetSignUpPolicy
by tenancy.tenants
——SignUpPolicy { tenants, accounts }the API (its api group)
GetTenant
by tenancy.tenants
tenantId: stringtenancy.tenant in tenantIdTenantRow { id, slug, name, status, suspension, mfaRequired, owners }a group permission
ListTenants
by tenancy.tenants
status?: TenantStatus
after?: string
limit?: number
—{ tenants: TenantRow[]; more: boolean }the platform

Listeners ​

ListenerOnSubmits
tenancy.tenants (read model, order -20)TenantCreated, TenantActivated, TenantRenamed, TenantSlugChanged, TenantSuspended, TenantReactivated, TenantDeleted, OwnerAdded, OwnerRemoved, MfaRequirementChanged, SignUpPolicyChanged—