Migrating from Clerk to Gate
Clerk's positioning leans React-component-first — <SignIn />, <UserButton />, <OrganizationSwitcher /> mount directly into your app's component tree, and Clerk owns the render pipeline. Gate is component-agnostic: a typed SDK that returns session objects you compose into your own UI (or into Gate Studio authoring artifacts if you want a visual layer). Migration is largely about replacing Clerk's rendered components with your own UI calling Gate's SDK.
If you haven't already, read the migration overview for the four-phase migration arc (capability audit → parallel-run setup → user-data migration → cutover) that applies across all vendors.
1. Capability mapping
| Capability | Clerk | Gate |
|---|---|---|
| Email + password sign-in | <SignIn /> component / signIn.create({ identifier, password }) | gate.signIn({ email, password }) |
| Magic link | Email link strategy on <SignIn /> | gate.passwordless.requestMagicLink → gate.passwordless.verifyMagicLink |
| OTP / email code | Email code strategy on <SignIn /> | gate.passwordless.requestOtp → gate.passwordless.verifyOtp |
| Social OAuth | OAuth strategies (Google / GitHub / etc.) | gate.signInWithProvider({ provider: 'google' }) → gate.completeSignIn() |
| SAML SSO | SAML (Pro plan) | gate.signInWithProvider({ provider: 'saml' }) |
| Passkeys / WebAuthn | Passkeys (GA) | See API → Auth §6 |
| MFA — TOTP | TOTP / authenticator app | End-user TOTP enrollment: POST /@<projectSlug>/gate/mfa/totp/enroll and .../totp/confirm |
| MFA — SMS | SMS verification | Not supported (SIM-swap risk; NIST 800-63B-4 deprecation) |
| Recovery codes | Backup codes | 10 single-use codes mandatory at MFA enrollment |
| Sessions | Server + browser session with JWT | Root + tenant two-tier model; see Session Model |
| Organizations | Built-in organization primitive with members + roles + invitations | Gate uses Kilimanjaro's project primitive as the multi-tenant container; project members + RBAC roles + invitations cover the same surface |
| User management UI | Clerk Dashboard + <UserButton /> hosted UI | Console (/admin/auth/members) for operators; Gate Studio for branded end-user UI |
| Branded hosted UI | Clerk theming + appearance prop | Gate Studio — drag-and-drop sign-in screen designer |
| Webhooks | Svix-backed webhooks for user.created etc. | Webhook subscriptions per Security §2.6 |
| Pricing | MAU-based, organizations gated above free | 50K MAU on Free; Unlimited on every paid tier; projects unlimited; identity not a metered axis on paid tiers |
The conceptual shift: Clerk thinks in organizations within a single app; Gate (under Kilimanjaro) thinks in projects within an org, where each project is its own sovereign data plane. If your Clerk app uses multi-org features for B2B tenancy, those map onto Kilimanjaro projects; if your Clerk app uses orgs as user-grouping inside a single tenant, those map onto Kilimanjaro user groups within a single project.
2. API-shape mapping
2.1 Sign-in
// Before — Clerk
import { useSignIn } from '@clerk/clerk-react';
const { signIn, setActive } = useSignIn();
const result = await signIn.create({
password: '...',
});
await setActive({ session: result.createdSessionId });
// After — Gate
import { createGateClient } from '@k9o/gate';
const gate = createGateClient({ mode: 'standalone', baseUrl: 'https://<orgSlug>.api.k9o.io', projectSlug: '<projectSlug>' });
const { data } = await gate.signIn({
password: '...',
});
// data.session.accessToken + data.session.refreshToken; data.user
Clerk's <SignIn /> component owns the render + form submission + redirect lifecycle. Gate's SDK returns the session object directly; you mount your own form and call gate.signIn from its submit handler.
2.2 Current user retrieval
// Before — Clerk
import { useUser } from '@clerk/clerk-react';
const { user, isSignedIn } = useUser();
// After — Gate
const { data: user } = await gate.whoami();
// or in React: keep your own session context, populated from the gate.signIn result
Clerk auto-refreshes the user in React context via the <ClerkProvider> wrapper. Gate has no provider component — you wire session state into your own state-management layer (React Context, Zustand, Redux, signals, whatever fits).
2.3 Token verification
Clerk's session token is verified via their JWKS endpoint or their backend SDK (@clerk/clerk-sdk-node). Gate's session token is a standard JWT verifiable via the per-project JWKS at <orgSlug>.api.k9o.io/@<projectSlug>/auth/jwks. The JWKS response is wrapped in the standard { data: { keys } } envelope, so a stock JOSE client cannot read it as is; verifyJwt from @k9o/gate unwraps it.
// Gate verification on a resource server
import { verifyJwt } from '@k9o/gate';
const result = await verifyJwt({
token,
jwksUrl: `${apiUrl}/@${projectSlug}/auth/jwks`,
allowedAlgorithms: ['EdDSA', 'RS256', 'ES256'],
expectedIssuer: issuer, // the iss claim of your Gate tokens (regional; read it from your tokens)
expectedAudience: projectId, // end-user tokens: aud is the project id
});
if (result.valid) { /* result.claims */ }
3. User-data migration
Export users from Clerk via their backend API (GET /v1/users) or their bulk-export tool. The fields you'll typically map:
| Clerk export field | Gate field |
|---|---|
id (user_xxx) | Map to a new Gate user; preserve old ID in customAttributes.clerk_id for cross-reference |
email_addresses[].email_address | email (primary) |
password_digest + password_hasher (if bcrypt/scrypt) | Importable via gate.users.import with the same hasher metadata; users sign in without password reset |
phone_numbers[] | phoneNumber (primary; secondary stored in customAttributes) |
external_accounts[] | Re-link via the project's Console IdP configuration after import; users re-consent the OAuth scope on first sign-in |
organizations[] + memberships[] | Map to Kilimanjaro projects + project memberships per the conceptual-shift note in §1 |
unsafe_metadata + public_metadata | customAttributes (single object; no public/unsafe split — apply your own policy through Controls) |
Test the import against a staging project first. Gate's gate.users.import supports dry-run mode ({ dryRun: true }) that returns per-row validation errors without actually creating users.
4. Code walkthrough — replacing <SignIn />
Clerk apps that use <SignIn /> as their only auth surface need to author a sign-in form. The minimum replacement:
import { useState } from 'react';
import { gate } from './gate-client';
export function SignInForm({ onSuccess }: { onSuccess: () => void }) {
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const [error, setError] = useState<string | null>(null);
async function handleSubmit(e: React.FormEvent) {
e.preventDefault();
setError(null);
try {
const { data } = await gate.signIn({ email, password });
// Store the session token however your app does (cookie, context, Zustand, etc.)
sessionStorage.setItem('k9o_token', data.session.accessToken);
onSuccess();
} catch (e) {
setError(e instanceof Error ? e.message : 'Sign-in failed');
}
}
return (
<form onSubmit={handleSubmit}>
<input value={email} onChange={(e) => setEmail(e.target.value)} type="email" />
<input value={password} onChange={(e) => setPassword(e.target.value)} type="password" />
<button type="submit">Sign in</button>
{error && <p role="alert">{error}</p>}
</form>
);
}
If you want a Clerk-quality hosted UI without authoring it yourself, configure Gate Studio — it renders a branded sign-in screen as an iframe / redirect surface analogous to Clerk's <SignIn /> flow.
5. Cutover checklist
| Step | Done when |
|---|---|
| Capability audit | Every Clerk surface listed in §1 mapped to a Gate equivalent (or replanned) |
| Parallel-run | Gate provisioned alongside Clerk; new sign-ups create accounts in both; verify identity via Gate; legacy logins still hit Clerk |
| User-data export | Clerk users exported via API or bulk-export tool |
| User-data import | gate.users.import run against the target Gate project; staging import passes; production import scheduled |
| Component replacement | Clerk components (<SignIn /> / <UserButton /> / <OrganizationSwitcher />) replaced with custom UI calling Gate's SDK (or Gate Studio iframe surfaces) |
| Token verifier migration | Resource servers verify against Gate's JWKS; Clerk JWKS removed |
| Cutover | DNS / routing flipped to Gate-only; Clerk webhooks disabled; Clerk tenant archived |
| Decommission | Clerk subscription cancelled after a 30-day verification window |
6. See also
- Migration overview — the four-phase migration arc.
- Gate API → Auth — the full Gate SDK surface.
- Gate Studio — visual sign-in authoring as a Clerk-component replacement.
- Pricing — Gate pricing model.