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>/...
| Component | Role |
|---|---|
<orgSlug> | Org subdomain — the customer-facing org identifier (see Slug Addressing) |
api.k9o.io | Platform 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:
| Surface | URL |
|---|---|
| Customer data plane | https://acme.api.k9o.io/@shop/data/orders/58391 |
| Gate end-user sign-in | https://acme.api.k9o.io/@shop/gate/signin |
| Function invoke | https://acme.api.k9o.io/@shop/functions/send-receipt/invoke |
| Org members (operator) | https://acme.api.k9o.io/members/u_xxx |
| Anonymous discovery | https://console.k9o.io/api/discovery/orgs |
| Operator sign-up | https://console.k9o.io/api/auth/sign-up |
| Platform health | https://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/melane, 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. Bareapi.k9o.iois also the platform's JWTissclaim — 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.
| Mode | URL shape | Org resolution | Wildcard DNS | Deployment scenarios |
|---|---|---|---|---|
subdomain (default) | https://acme.api.k9o.io/@shop/... | Host header | Required (*.api.k9o.io) | Cloud and sovereign-cloud deployments; local dev via .localhost |
path-prefix | https://kilimanjaro.acme.local/acme/@shop/... | First path segment | Not required (single A record) | LAN multi-tenant — internal hosting providers; rare |
single-org | https://kilimanjaro.acme.local/@shop/... | K9O_DEFAULT_ORG config | Not 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.
| Production | Local dev |
|---|---|
https://acme.api.k9o.io | http://acme.api.localhost:3000 |
https://acme.console.k9o.io | http://acme.console.localhost:3000 |
https://console.k9o.io/api/discovery/orgs | http://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.