Regions & residency
Where a project's data lives is a first-class decision, not a side effect of where the developer signed up. Every project carries a region field set at creation, immutable thereafter. Cross-border data movement is opt-in and audited — never accidental. This page covers the residency model, the immutability rule, the control-plane / data-plane split, and the operational paths for jurisdiction-specific deployments.
1. Region as a sovereignty pin
Every project pins to exactly one region at creation:
POST <orgSlug>.api.k9o.io/projects
{
"displayName": "Production",
"region": "de01",
"custodyMode": "BYOK",
...
}
The region field is drawn from a closed enum of sovereignty-pinned regions. Each region maps to a specific jurisdiction (national or supranational) and an underlying sovereign-cloud substrate (compute + storage + network within that jurisdiction). A project pinned to de01 (Falkenstein) runs on EU-based infrastructure inside the EU's data-protection regime; a project pinned to us01 (Virginia) runs on US-based infrastructure under US data-protection rules.
A region code is four characters: a country code and a two-digit sequence. It identifies the country, never the bloc or the zone (both come from the table below). A code is immutable and is never reused for a different place. The same code is used everywhere a region appears: API inputs and outputs, error messages, JWT claims, audit and billing events, SDK enums and the Console. A project's city comes from the display name in the table, not from the code.
Two groupings sit on top of the region, and they answer different questions:
- Bloc (legal). A bloc is one country, or a set of countries that share data-protection law and treaties. Every region belongs to exactly one bloc. Moving data between regions inside one bloc needs no consent step.
- Zone (pricing). A zone is a free trade area or single market. It sets the egress price tier. A region can belong to more than one zone. The list of zones is closed.
Neither comes from the city, which is only a display label. Bloc and zone slugs are two to twelve lowercase letters, so a slug is never mistaken for a region code.
The region enum covers 14 sovereignty-pinned regions:
| Region | City, country | Bloc | Zone | Former name |
|---|---|---|---|---|
de01 | Falkenstein, Germany | eu | eu | eu-central-1 |
uk01 | London, United Kingdom | uk | uk | uk-south-1 |
us01 | Virginia, United States | us | na | us-east-1 |
us02 | Texas, United States | us | na | us-central-1 |
us03 | Oregon, United States | us | na | us-west-2 |
ca01 | Montreal, Canada | ca | na | ca-central-1 |
ng01 | Lagos, Nigeria | ng | afcfta | af-west-1 |
za01 | Johannesburg, South Africa | za | afcfta | af-south-1 |
sg01 | Singapore | sg | apac | ap-southeast-1 |
au01 | Sydney, Australia | au | apac | ap-southeast-2 |
jp01 | Tokyo, Japan | jp | jp | ap-northeast-1 |
in01 | Mumbai, India | in | in | ap-south-1 |
ae01 | Dubai, United Arab Emirates | ae | me | me-central-1 |
br01 | São Paulo, Brazil | br | sa | sa-east-1 |
The other zone is the fallback for a region with no zone. It matches nothing, itself included, so traffic between two such regions prices as inter-zone.
The former names are listed only so you can read older logs and references. They are no longer accepted: a request that sends one is rejected like any other unknown value.
The egress-pricing tier for any pair of regions comes from their zones: same region → intra-region; different regions that share at least one zone → intra-zone; regions that share no zone → inter-zone. Singapore to Sydney crosses a bloc but shares the apac zone, so it prices intra-zone. The full pricing mapping is documented on the platform's pricing surface.
2. The immutability rule
A project's region cannot be changed via API. PATCH <orgSlug>.api.k9o.io/projects/<projectSlug> with a region field returns INVALID_REQUEST_SHAPE (400) with context.reason: "REGION_IS_IMMUTABLE".
Why immutable? Sovereignty boundaries do not move on demand. A project pinned to de01 participates in the EU's data-protection regime as a structural fact, not a configurable preference. Allowing API-driven re-pinning would mean a single API call moves customer data across a sovereignty boundary — exactly the property the platform's positioning forecloses.
Re-pinning is operationally a project recreation: the customer creates a new project in the desired region, migrates data using their own tooling (the platform provides export endpoints; cross-project data movement is the customer's responsibility), and decommissions the old project. The operational friction is by design — it forces the migration to be a deliberate, audited, customer-led decision.
For customers whose business genuinely needs to re-pin a live project (extremely rare; typically driven by regulatory disposition changes), the operational path is a support-ticket-driven re-shard pipeline. This is not a customer-facing API; it's a one-off operational procedure with platform-side validation.
3. Control plane vs data plane
The platform separates control-plane operations from data-plane operations, and they live in different regions:
| Plane | What lives here | Region |
|---|---|---|
| Control plane | Org / project / member metadata, billing, IdentityProvider configuration, extension registry, audit log | Pinned to the org's control-plane region at org creation; immutable |
| Data plane | Documents, files, real-time subscriptions, function executions, query results | Pinned per project at project creation; immutable |
The control plane and data plane regions are decoupled. An org operating projects across three jurisdictions has a single control-plane region for operational visibility (audit log + admin Console + billing); each project's data stays inside its declared jurisdiction independently.
Control-plane region defaults to the region selected at org signup but can be set explicitly via the org-creation payload. Like project region, it is immutable after creation.
4. Cross-border policy
By default, data does not cross region boundaries. A project pinned to de01:
- Stores documents, files, and database state in
de01infrastructure. - Routes function executions to
de01compute. - Issues JWTs with
proj_idcarrying the project's region context. - Emits audit events into the project's
de01data-plane audit table (with a copy to the org's control-plane region).
Cross-border movement is opt-in via three mechanisms, each audited:
| Mechanism | Use |
|---|---|
| Cross-region replication | Project-level configuration declaring read-replica regions for high-availability or cross-jurisdiction analytics; replication is one-way (declared) and audit-attributed |
| Audit-log export | Exports to a customer-supplied SIEM endpoint cross regions per the SIEM configuration; the export is the cross-border path, not the project's primary data |
| Manual export | Customer-initiated data.export operations produce signed URLs that can be retrieved from any region; the export operation itself is logged |
There is no "best-effort" or "incidental" cross-border path. Every byte of customer data that leaves the declared region does so through an audited, customer-declared mechanism.
5. Region context in tokens and requests
Every JWT carries the project's region context. Every API request carries the project context via the URL grammar (<orgSlug>.api.k9o.io/@<projectSlug>/...; see URL grammar). The gateway validates:
- The token's
proj_idclaim matches the requested project context. - The targeted resource (the document being read, the file being uploaded, the function being invoked) lives in the project's region.
- The caller's role taxonomy and JSON-policy evaluation permit the operation.
A request that targets a resource outside the project's region is rejected at the gateway before any pillar handler runs. This isn't a soft-warning; it's a structural rejection — the gateway has no path to route the request to a resource outside the project's pinned region.
6. In-country deployments
For customers whose compliance regime requires deployment inside a specific country we don't list as a public region, the platform supports private-jurisdiction deployments by contract (the Sovereign Control and Private Perimeter deployment architectures). The process:
- Customer surfaces the jurisdiction requirement to the platform team.
- Platform confirms a sovereign-cloud substrate is available in the country (compute + storage + network from a vendor satisfying the customer's compliance regime).
- A dedicated platform instance is provisioned in-country; the customer's org and projects bind to the private region as their region pin.
- The same API contract applies; the only difference is the underlying jurisdiction and the deployment topology (private tenant vs shared multi-tenant).
Private-jurisdiction deployments are not a customer-facing self-serve API. They are provisioned by contract with platform-side jurisdiction validation.
7. Region selection
Every project can pin any region in the platform's region set at creation; region selection is not scaled by plan. Private-jurisdiction deployments are available by contract (see §6). The deployment architectures differ in topology, not in what a project may select:
| Deployment model | Topology |
|---|---|
| Cloud | Shared, platform-managed regions |
| Sovereign Control | A dedicated, isolated tenant in a platform-managed region |
| Private Perimeter | Sovereign in-country deployment on dedicated substrate |
Each region is backed either by a hyperscaler (platform-managed) or, where no hyperscaler serves the jurisdiction, by an in-country sovereign deployment. The regions in the set and the pricing-zone mapping live on the pricing surface.
8. See also
- API → Conventions — project-context resolution via the URL grammar.
- API → Data — data-plane operations the region pin governs.
- API → Security — audit-log retention and cross-region export mechanics.
- Architecture → Architecture — control-plane / data-plane split.
- Pricing — region set and pricing-zone mapping.
- Global Analytics Without Global Leaks — why a cross-region aggregate never becomes a channel back to one subject's data, and how Statistical Disclosure Control governs the crossing.