Skip to main content

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​

CapabilityClerkGate
Email + password sign-in<SignIn /> component / signIn.create({ identifier, password })gate.signIn({ email, password })
Magic linkEmail link strategy on <SignIn />gate.passwordless.requestMagicLink → gate.passwordless.verifyMagicLink
OTP / email codeEmail code strategy on <SignIn />gate.passwordless.requestOtp → gate.passwordless.verifyOtp
Social OAuthOAuth strategies (Google / GitHub / etc.)gate.signInWithProvider({ provider: 'google' }) → gate.completeSignIn()
SAML SSOSAML (Pro plan)gate.signInWithProvider({ provider: 'saml' })
Passkeys / WebAuthnPasskeys (GA)See API → Auth §6
MFA — TOTPTOTP / authenticator appEnd-user TOTP enrollment: POST /@<projectSlug>/gate/mfa/totp/enroll and .../totp/confirm
MFA — SMSSMS verificationNot supported (SIM-swap risk; NIST 800-63B-4 deprecation)
Recovery codesBackup codes10 single-use codes mandatory at MFA enrollment
SessionsServer + browser session with JWTRoot + tenant two-tier model; see Session Model
OrganizationsBuilt-in organization primitive with members + roles + invitationsGate uses Kilimanjaro's project primitive as the multi-tenant container; project members + RBAC roles + invitations cover the same surface
User management UIClerk Dashboard + <UserButton /> hosted UIConsole (/admin/auth/members) for operators; Gate Studio for branded end-user UI
Branded hosted UIClerk theming + appearance propGate Studio — drag-and-drop sign-in screen designer
WebhooksSvix-backed webhooks for user.created etc.Webhook subscriptions per Security §2.6
PricingMAU-based, organizations gated above free50K 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({
identifier: '[email protected]',
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.

Clerk<SignIn />owns render, form, redirectClerk sessionserver and browser, JWTClerk JWKSor backend SDKGateYour own formcalls gate.signIn on submitSession objectaccess + refresh tokenPer-project JWKSverifyJwt from @k9o/gate
The rendered Clerk component becomes your own form calling the Gate SDK, and token verification moves to the per-project JWKS.

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 fieldGate field
id (user_xxx)Map to a new Gate user; preserve old ID in customAttributes.clerk_id for cross-reference
email_addresses[].email_addressemail (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_metadatacustomAttributes (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​

StepDone when
Capability auditEvery Clerk surface listed in §1 mapped to a Gate equivalent (or replanned)
Parallel-runGate provisioned alongside Clerk; new sign-ups create accounts in both; verify identity via Gate; legacy logins still hit Clerk
User-data exportClerk users exported via API or bulk-export tool
User-data importgate.users.import run against the target Gate project; staging import passes; production import scheduled
Component replacementClerk components (<SignIn /> / <UserButton /> / <OrganizationSwitcher />) replaced with custom UI calling Gate's SDK (or Gate Studio iframe surfaces)
Token verifier migrationResource servers verify against Gate's JWKS; Clerk JWKS removed
CutoverDNS / routing flipped to Gate-only; Clerk webhooks disabled; Clerk tenant archived
DecommissionClerk subscription cancelled after a 30-day verification window

6. See also​