Session Model
Operator-scope identity (sign in, switch orgs, manage account profile) lives on the Console root — console.k9o.io. Tenant-scope identity (operate within a specific org's data plane, dashboards, settings) lives on the org subdomain — <orgSlug>.console.k9o.io. The two are bridged by a signed single-use exchange ticket that keeps the operator's sign-in cost paid once across every tenant they access.
This page covers the two-tier session structure, the exchange flow between root and tenant, the sign-out cascade, MFA step-up semantics, and the API-key path for programmatic callers.
1. Two tiers — root and tenant
| Tier | Domain scope | Cookie | JWT audience | Lifetime | Established by |
|---|---|---|---|---|---|
| Root session | console.k9o.io only | _k9o_root (HttpOnly + Secure + SameSite=Lax) | console.k9o.io | 1–2h rolling | Password + MFA at sign-in |
| Tenant session | <orgSlug>.console.k9o.io only | _k9o_tenant (HttpOnly + Secure + SameSite=Lax) | <orgSlug>.api.k9o.io | Standard refresh per session policy | Exchange from root session |
The root session is the identity anchor — it proves "you are the operator who signed in with these credentials and this MFA factor." The tenant session is the operating context — it proves "you have a current, MFA-fresh authorisation to act inside this specific org."
The two cookies cannot read each other (different domains, browser-enforced); the two JWTs have different audiences (different gateways accept them). An attacker with one cookie cannot escalate to the other without going back through the exchange flow.
2. The exchange flow
When an operator signed into the root domain navigates to a tenant, the platform mints a signed single-use exchange ticket and redirects the operator to the tenant subdomain. The full flow:
- Operator clicks a tenant tile on the root Console (
console.k9o.io) - Console issues
POST console.k9o.io/exchange { org: "acme" }— the root cookie is present in the request - Server validates the root cookie, looks up the operator's
org_memberships, and confirms the operator is a member of the requested org - Server mints a signed exchange ticket — 60-second expiry, single-use, tracked in
k9o_platform.exchange_ticket_consumedto prevent replay - Response is a 302 redirect to
https://acme.console.k9o.io/auth/exchange?ticket=<token> - Tenant gateway validates the ticket, mints the tenant JWT, sets the tenant cookie on
acme.console.k9o.io - Tenant gateway 302s to the tenant dashboard
Total: ~150ms over the wire, two HTTP redirects, zero credential prompts. The operator clicks a tile and lands inside the tenant.
2.1 Cross-tenant navigation
When the operator is already inside one tenant and clicks a link to a different tenant, the flow is the same — three redirects (out of the current tenant, through the root exchange, into the new tenant), ~200–300ms total, no credential prompts. The root session is the persistent identity that makes this fast.
2.2 Direct tenant link
When the operator clicks a deep link to a tenant URL without an active root session, the platform redirects them to root sign-in, completes authentication and MFA, then exchanges into the requested tenant — same flow, with the sign-in step in front. Once they have a root session, subsequent cross-tenant clicks compose against the existing root identity.
3. Sign-out cascade
Sign-out semantics differ by which session is being closed:
| Action | Effect |
|---|---|
| Tenant sign-out | Tenant cookie invalidated on <orgSlug>.console.k9o.io; the operator's tenant JWT is no longer accepted at the tenant gateway. Root session continues. Other tenants the operator is signed into remain active. |
| Root sign-out | Root cookie invalidated on console.k9o.io; a cascade fan-out invalidates every tenant refresh-token the operator currently holds. Every tenant session the operator has open is terminated. |
The cascade on root sign-out is the "log out everywhere" affordance. An operator on a shared device closes the root session and is confident no tenant session lingers — the platform fans out the invalidation across every tenant gateway.
4. MFA step-up
A tenant can require stricter MFA freshness than the root session provides. When the operator's tenant JWT no longer meets the tenant's freshness policy (the MFA factor used at sign-in has aged past the tenant's threshold), the tenant gateway responds with a redirect to the root MFA challenge.
The flow:
- Operator action at the tenant requires fresh MFA per the tenant's policy
- Tenant gateway returns a 302 to
https://console.k9o.io/auth/mfa/step-up?return=<tenant-url> - Operator completes MFA at root — TOTP, hardware key, push notification, per their account configuration
- Root mints a fresh MFA claim on the root session
- Re-fires the exchange to the original tenant, embedding the fresh MFA claim in the new tenant JWT
- Operator returns to the tenant with fresh MFA
A single MFA prompt at root covers every tenant with comparable freshness policy — the operator does not re-MFA at each tenant they navigate to. Stricter-policy tenants (e.g., a regulated-data tenant) may require fresher claims; the step-up at root is the single source for that freshness.
5. API keys — the programmatic path
The exchange flow is interactive-only. Browser callers see the redirects and cookies. Programmatic callers — server-to-server SDKs, batch processors, cron jobs, CI pipelines — use a different mechanism entirely.
API keys:
- Header form:
Authorization: Bearer k9o_<base62> - Tenant-scoped: an API key binds to a specific org and project at creation time; it cannot be used to access any other tenant
- Long-lived: API keys do not roll on the session-refresh schedule; they live until explicitly revoked
- Revocable: revocation is immediate and unilateral; the next request after revocation receives
401 Unauthorized - Audit-attributed: every API-key call is logged with the key's identifier in the audit ledger; the operator who issued the key is part of the forensic chain
API keys are the right tool for code that does not have a human in the loop. The cookie-and-exchange flow is the right tool for code that does. Mixing the two (a backend service holding a browser cookie, an interactive tool fumbling with API keys) is the wrong shape; the platform's identity model splits cleanly along this seam.
6. Operational patterns
- Idle root session is acceptable across an operator's working session; the rolling 1–2h lifetime keeps it tight without forcing re-sign-in on every tenant click.
- Idle tenant session rolls on standard refresh per the tenant's policy; tenants with stricter policy roll shorter.
- Cross-device is intentionally not session-shared. An operator signed in on two devices has two independent root sessions; revoking one does not revoke the other (use root sign-out cascade if you want fan-out invalidation).
- Sign-out on a stolen-device scenario is the root sign-out cascade — invalidates every tenant token the operator held, regardless of which device the tenant session lived on.
7. See also
- Routing Modes — the URL grammar that the tenant subdomain composes against.
- Slug Addressing — how
<orgSlug>resolves through the exchange flow. - Custom Domains — a capability of every project for custom tenant domains; the session model carries through with appropriate cookie domain rewrites.
- Security → Identity-Aware Kernel — the cryptographic substrate that backs the session signatures and the MFA factors.