Skip to main content

Migration

Migrating to Kilimanjaro typically means consolidating multiple vendors — one for identity, one for the database, one for secrets, one for analytics — into a single platform with one API surface. The mechanics vary by what you're consolidating from; the four-phase arc is consistent.

1. What you're migrating from​

Customers come to Kilimanjaro from four common starting points:

Starting pointSurfaceGuide
Hosted identity vendor (Auth0, Clerk, Stytch, WorkOS, Okta, Entra ID, Google Workspace)Auth surface only — keep your existing data layer; adopt Gate StandaloneGate Migration — Auth0 sub-guide is published; other vendors use the same migration shape
BaaS platform (Supabase, Firebase, Hasura, Convex, AWS Amplify)Full platform — consolidate identity + database + functions onto Kilimanjaro Native§3.2 below
In-house auth stackAuth surface — replace your hand-rolled identity layer with GateGate Migration general framing
Kilimanjaro v1Engineering-operated cutover — coordinated by the platform team§4 below

The right migration shape depends on which axis you're consolidating. A team replacing only their identity vendor follows the Gate Standalone path. A team adopting the full Sovereign Stack follows the Native path with corresponding data-plane migration work.

2. The four-phase migration arc​

Every migration follows the same four phases regardless of starting point:

Phase 1Capability auditsized by what youactually usePhase 2Parallel-run setupprovisioned and tested,no live traffic yetPhase 3Data migrationvalidate againstpre-migration countsPhase 4Cutovergradual traffic shift,not a flipCutover stepsStart smalltraffic fractionWidenas metrics holdCut overto 100%Monitorone renewal cycleDecommissionsource platform
Every migration runs the same four phases, and cutover widens traffic step by step before the source platform is retired.

Phase 1 — Capability audit​

Before any code changes, audit the surface you're replacing:

  • Which capabilities does your live application actually exercise? Migration is sized by what you use, not what your vendor account supports.
  • What's the user / data / configuration footprint? Active users, data volume, identity-provider connections, custom logic at each integration point.
  • What custom behaviour rides on the current vendor? Hand-rolled webhook handlers, custom claims, vendor-specific quirks your code depends on.
  • What's the compliance posture you need to maintain? Audit-log retention, SIEM integration, regulatory framework requirements, data-residency constraints.

The capability audit is what gates Phase 2 — without it the parallel-run is built on assumptions rather than measurement.

Phase 2 — Parallel-run setup​

Provision Kilimanjaro alongside your existing stack without cutting over:

  • A new project in the target region with the appropriate custody mode.
  • For identity migration: identity providers matching your existing federated connections, attribute mapping configured, group sync mode chosen.
  • For data migration: collections and schemas matching your existing data shape, JSON policies authored.
  • For observability continuity: SIEM forwarding to your existing observability surface, audit-log retention configured.

At Phase 2 close, no live traffic flows through Kilimanjaro yet. The platform is provisioned and tested; integration tests pass; the capability audit's findings are verified against the live configuration.

Phase 3 — Data migration​

The mechanics vary by what you're migrating:

  • Identity — bulk hash import (preserve existing hashes; Argon2id native, bcrypt re-hashed on first sign-in) or federated-migration window (point Kilimanjaro at your existing vendor as an OIDC provider during transition). Per Gate Migration §3.
  • Data records — export from the source platform; import into the project's data plane. Tooling varies by source platform; the platform provides a bulk-import endpoint with progress streaming and validation.
  • Files / object storage — copy from the source storage layer into the platform's object storage; the platform provides a bulk-upload endpoint with checksum validation.
  • Secrets / keys — if upgrading to BYOK or HYOK custody, provision the keys per the Kibo onboarding flow; re-key existing ciphertexts per the custody-transition mechanics.

Data-migration discipline: validate post-migration against pre-migration counts + spot-check semantic correctness on a representative sample before opening live traffic to the new surface.

Phase 4 — Cutover​

Cutover is a gradual traffic shift, not a flip:

  1. Enable Kilimanjaro for a fraction of traffic (feature flag, A/B percentage, single application tier).
  2. Monitor sign-in success rate + data-operation success rate + audit-event throughput + error-rate-by-endpoint.
  3. Widen the Kilimanjaro fraction as the metrics hold.
  4. Cut over to 100%.
  5. Monitor for one full session-renewal cycle (~30 days for refresh-token TTL).
  6. Decommission the source platform.

Most migrations cut over within two to four weeks of Phase 2 commencement. Identity-only migrations are typically shorter; full-platform migrations (BaaS → Native) are longer because the data plane work runs alongside the auth work.

3. Migration sources​

3.1 From a hosted identity vendor → Gate Standalone​

The most common migration shape: you keep your existing data layer (PostgreSQL, MongoDB, DynamoDB, whatever) and adopt Gate as the identity surface. The migration is API-shape mapping (existing vendor SDK → @k9o/gate SDK) + user-data migration + cutover. See Gate Migration for the per-vendor walkthroughs.

3.2 From a BaaS platform → Native​

The biggest migration shape: you're consolidating identity + database + functions onto the Sovereign Stack. The major axes:

AxisSource platformKilimanjaro Native
IdentityThe BaaS platform's identity surfaceGate Native with automatic data-layer scoping turned on
DatabaseSource platform's hosted Postgres / Firestore / DynamoDBData pillar — Postgres-based with collections + JSON-policy enforcement
StorageSource platform's object storageData pillar's object-storage surface
FunctionsSource platform's serverless functionsCompute pillar — edge tier + platform tier
Real-timeSource platform's subscriptions / channelsData pillar's real-time subscription surface
Auth-aware queriesRow-level security policies hand-authoredAutomatic data-layer scoping — identity is the binding identity for every query by infrastructure

The Native migration unlocks the structural property that distinguishes Kilimanjaro from a hosted BaaS: scoping happens by infrastructure rather than by code discipline, so a developer who forgets to apply a WHERE user_id = ... clause never leaks data — the gateway already enforced it.

3.3 From an in-house auth stack → Gate Standalone​

For teams who've hand-rolled identity (custom JWT issuance, custom session management, custom MFA), Gate Standalone replaces the entire stack with the same shape adopted by customers migrating from hosted identity vendors. The migration is:

  1. Identify which platform-side mechanics your stack implements (sign-in / sign-up / refresh / MFA / IdP federation / transactional email).
  2. Replicate the surface area through Gate's configuration.
  3. Migrate users (bulk hash import or federated-migration window).
  4. Cut over per Phase 4.

The in-house migration is typically the most variable in scope — every hand-rolled stack is different — but the Phase 1 capability audit usually identifies a smaller surface than the team expects, since most in-house stacks were built to a specific operational need rather than the full identity-vendor surface area.

4. From Kilimanjaro v1​

v1 → v2 migration is engineering-operated server-side. Customers experience it as a coordinated cutover rather than a tool they run. Existing v1 customers receive timeline + comms cadence from the platform team; the migration window includes:

  • Pre-cutover state validation (residency posture, encryption posture, audit-trail continuity).
  • A scheduled cutover window (typically off-hours per the customer's region).
  • Post-cutover validation steps surfaced to the customer for sign-off.

Rollback options are pre-staged on the platform side; the customer's involvement is limited to validation and disposition.

For customers on v1, the cutover is driven by the v1 EOL schedule. Specifics communicated separately by the platform team.

5. See also​