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 point | Surface | Guide |
|---|---|---|
| Hosted identity vendor (Auth0, Clerk, Stytch, WorkOS, Okta, Entra ID, Google Workspace) | Auth surface only — keep your existing data layer; adopt Gate Standalone | Gate 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 stack | Auth surface — replace your hand-rolled identity layer with Gate | Gate Migration general framing |
| Kilimanjaro v1 | Engineering-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 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:
- Enable Kilimanjaro for a fraction of traffic (feature flag, A/B percentage, single application tier).
- Monitor sign-in success rate + data-operation success rate + audit-event throughput + error-rate-by-endpoint.
- Widen the Kilimanjaro fraction as the metrics hold.
- Cut over to 100%.
- Monitor for one full session-renewal cycle (~30 days for refresh-token TTL).
- 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:
| Axis | Source platform | Kilimanjaro Native |
|---|---|---|
| Identity | The BaaS platform's identity surface | Gate Native with automatic data-layer scoping turned on |
| Database | Source platform's hosted Postgres / Firestore / DynamoDB | Data pillar — Postgres-based with collections + JSON-policy enforcement |
| Storage | Source platform's object storage | Data pillar's object-storage surface |
| Functions | Source platform's serverless functions | Compute pillar — edge tier + platform tier |
| Real-time | Source platform's subscriptions / channels | Data pillar's real-time subscription surface |
| Auth-aware queries | Row-level security policies hand-authored | Automatic 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:
- Identify which platform-side mechanics your stack implements (sign-in / sign-up / refresh / MFA / IdP federation / transactional email).
- Replicate the surface area through Gate's configuration.
- Migrate users (bulk hash import or federated-migration window).
- 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
- Gate Migration — migration paths from third-party identity vendors.
- Gate → Migrating from Auth0 — first per-vendor sub-guide.
- Architecture → Architecture — the structural framing migrators target.
- Identity-Aware Kernel — Standalone vs Native consumption paths.
- Regions & residency — region-pin decisions for the target project.
- API → Data — data plane the migration targets for Native paths.
- Guides → Sovereignty — sovereignty posture decisions during migration.
- Guides → Observability — audit-log continuity during cutover.