Skip to main content

Routing Modes

Every customer-facing URL on Kilimanjaro follows one grammar — but the platform supports three operational deployments of that grammar to match the customer's hosting context. The grammar is consistent across all three modes; only the mechanism that resolves "which org owns this request" varies.

This page covers the canonical URL shape, the three routing modes that consume it, and the local-development pattern that lets you build against any of the three modes without DNS configuration.

1. The canonical URL grammar​

https://<orgSlug>.api.k9o.io/@<projectSlug>/<sub-resource>/...
ComponentRole
<orgSlug>Org subdomain — the customer-facing org identifier (see Slug Addressing)
api.k9o.ioPlatform API host (Cloud subdomain mode)
@<projectSlug>Project marker at path position 1 — the @ prefix disambiguates the project from any sub-resource segment
<sub-resource>The data plane, function invoke, gate path, or other API surface

Disambiguation under this grammar: the subdomain carries the org slug; the @-prefix at path position 1 carries the project slug; the path segment /data/ marks the customer data-plane boundary.

Worked examples:

SurfaceURL
Customer data planehttps://acme.api.k9o.io/@shop/data/orders/58391
Gate end-user sign-inhttps://acme.api.k9o.io/@shop/gate/signin
Function invokehttps://acme.api.k9o.io/@shop/functions/send-receipt/invoke
Org members (operator)https://acme.api.k9o.io/members/u_xxx
Anonymous discoveryhttps://console.k9o.io/api/discovery/orgs
Operator sign-uphttps://console.k9o.io/api/auth/sign-up
Platform healthhttps://api.k9o.io/health
Console UI (per-tenant)https://acme.console.k9o.io/...
Root Console (org-switcher)https://console.k9o.io/

The platform separates five surfaces by host, each with a specific job:

  • Console-app API — console.k9o.io/api/*. The operator's pre-tenant lane: sign-up, sign-in, discovery, the cross-org /me lane, and cross-tenant org operations. Same-origin with the Console UI so the session cookie is CORS-free.
  • Console UI — console.k9o.io/ (without /api/). The org-switcher landing and any other operator-facing UI that runs before a tenant is chosen.
  • Per-tenant Console UI — <orgSlug>.console.k9o.io/.... The Console once you're inside an org.
  • Tenant API — <orgSlug>.api.k9o.io/@<projectSlug>/.... Project-scoped data, control, and runtime — everything the post-tenant SDK calls.
  • Platform API — api.k9o.io/*. Genuinely cross-tenant platform services (health, marketplace catalogue, the extensions hub, cross-org orchestration). Not an operator-anchor. Bare api.k9o.io is also the platform's JWT iss claim — a symbolic platform identifier, independent of any specific operator host.

The bare-host appearance in the JWT issuer string is what creates the most common confusion: seeing iss: "https://api.k9o.io" in a token can read as "bare api.k9o.io is where operators sign in." It isn't. The operator-anchor lane is console.k9o.io/api/*.

2. The three routing modes​

The platform reads K9O_ROUTING_MODE at startup to choose how it resolves the org context. The grammar customers see does not change; only the resolution mechanism varies.

ModeURL shapeOrg resolutionWildcard DNSDeployment scenarios
subdomain (default)https://acme.api.k9o.io/@shop/...Host headerRequired (*.api.k9o.io)Cloud and sovereign-cloud deployments; local dev via .localhost
path-prefixhttps://kilimanjaro.acme.local/acme/@shop/...First path segmentNot required (single A record)LAN multi-tenant — internal hosting providers; rare
single-orghttps://kilimanjaro.acme.local/@shop/...K9O_DEFAULT_ORG configNot required (single A record)Private Perimeter single-tenant appliance — most common Private Perimeter; customer self-hosted Docker Compose

The same SDK, the same CLI, the same spec, the same grammar serve all three modes. Application code does not need to know which routing mode the deployment runs under — the SDK's base-URL configuration captures the difference at init time, and every API call composes against that base URL.

3. Mode selection — when each applies​

3.1 subdomain (default)​

Cloud deployments and the standard local-development happy path. The platform owns *.api.k9o.io and serves any <orgSlug>.api.k9o.io host. Org resolution is a host-header lookup against the slug table.

Use subdomain when:

  • You are running on the Cloud — subdomain mode is the only option there
  • You are running on a sovereign-cloud deployment with the platform's standard sovereign-cloud substrate
  • You are doing local development against the platform — see §4

3.2 path-prefix​

A LAN multi-tenant deployment where the operator cannot or chooses not to configure wildcard DNS. The platform handles every host name but reads the org from the first path segment.

Use path-prefix when:

  • You are an internal hosting provider running Kilimanjaro on a LAN against a single host
  • You cannot configure wildcard DNS in the environment
  • You want a single A record to serve every tenant

Rare in production. The default is subdomain.

3.3 single-org​

A single-tenant Private Perimeter appliance where the org is implicit. The platform reads K9O_DEFAULT_ORG from configuration and treats every request as scoped to that org. URLs do not carry an org subdomain or path prefix; the project is still addressed by @<projectSlug>.

Use single-org when:

  • You are running a Private Perimeter air-gapped appliance for a single customer org
  • You are running a self-hosted Docker Compose deployment for development or staging
  • You want the simplest URL surface — no DNS configuration beyond the one host

This is the most common Private Perimeter shape.

4. Local development — the .localhost TLD​

Production URLs map to local development with a single substitution: replace k9o.io with localhost. The .localhost TLD is reserved by RFC 6761; every operating system resolves any *.localhost host to 127.0.0.1 without DNS configuration.

ProductionLocal dev
https://acme.api.k9o.iohttp://acme.api.localhost:3000
https://acme.console.k9o.iohttp://acme.console.localhost:3000
https://console.k9o.io/api/discovery/orgshttp://console.localhost:3000/api/discovery/orgs

Zero /etc/hosts edits, zero reverse-proxy, zero local CA for the happy path. The same SDK calls that compose against acme.api.k9o.io in production compose against acme.api.localhost:3000 in local dev — only the base URL changes.

4.1 Dev-mode escape hatch​

For local tools that handle subdomain routing poorly (some test runners, some HTTP clients), the platform accepts an X-K9o-Org-Slug header in dev mode and reads the org from there. The header is gated by NODE_ENV and rejected in production.

This is a pure ergonomics escape hatch; the canonical local-dev pattern is .localhost subdomain.

5. API version header​

The K9o-API-Version header is accepted on every request and the SDKs send it with their release version, but the gateway does not select a surface from it. It is informational: you cannot pin an API version with it. See Conventions §5.1.

6. See also​

  • Slug Addressing — the identifier scheme that feeds into the URL grammar.
  • Session Model — root and tenant sessions; the exchange flow between root domain and org subdomain.
  • Project Selection & Access Requests — the auth-flow lifecycle from email discovery through project selection, and the access-request resource.
  • Custom Domains — a capability of every project for replacing the platform subdomain with the customer's own.
  • Regions & residency — region pinning and the sovereignty implications.