Cross-device pairing

Your user pays on the companion site. Minutes later they put on the glasses, tap Start Pairing, and link the two devices: on the same network, they tap their Display once on the companion's /pair page and approve on the glasses; on a different network, they type the short code the glasses show and confirm a 2-digit number on the phone. Either way they're signed in. No password on a D-pad. No QR to scan. This is the bit of GlassKit that doesn't exist in Meta's free starter and is hardest to wire correctly.

The primary mechanism is same-network device pairing with an on-glasses approval step. The glasses register an anonymous pairing session tagged with their network's egress IP and wait; the user's phone, on the same Wi-Fi and already signed into the companion, sees that Display listed on /pair and taps it; the glasses prompt "Pair with <your account>? Yes / No" and the wearer taps Yes. Only then is a Clerk Sign-In Ticket minted server-side and exchanged via signIn.create. The ticket never crosses a URL boundary, and the consent decision lives on the glasses, where only the wearer can see and make it.

When the phone and glasses aren't on the same network (phone on cellular, guest Wi-Fi), same-network discovery can't link them. For that there's a code fallback: the glasses always show a short code and a verify number on the waiting screen, the user types the code into /pair and confirms that the verify number matches, and the same Sign-In Ticket is minted. The verify-match moves the consent onto the phone (see The code fallback below).

The flow at a glance

The pieces

export const createPairingSession = mutation({
  args: { glassesIp: v.string() },
  handler: async (ctx, { glassesIp }) => {
    await rateLimiter.limit(ctx, "pairingRegister", {
      key: glassesIp,
      throws: true,
    });

    const sessionId = generateSessionId(); // 120-bit, URL-safe
    const code = randomCode(); // unique 6-char code
    const verifyCode = generateVerifyCode(); // 2-digit verify number
    const expiresAt = Date.now() + SESSION_EXPIRES_SECONDS * 1_000;
    await ctx.db.insert("pairing_sessions", {
      sessionId,
      code,
      verifyCode,
      glassesIp,
      status: "pending",
      createdAt: Date.now(),
      expiresAt,
    });

    return { sessionId, code, verifyCode, expiresAt };
  },
});

export const watchPairingSession = query({
  args: { sessionId: v.string() },
  handler: async (ctx, { sessionId }) => {
    const session = await ctx.db
      .query("pairing_sessions")
      .withIndex("by_session", (q) => q.eq("sessionId", sessionId))
      .unique();
    if (!session) return null;
    // status: "pending" → "claimed" → "confirmed" → "ready"
    return {
      status: session.status,
      claimingLabel: session.claimingLabel ?? null,
    };
  },
});

export const pendingSessionsForIp = query({
  args: { glassesIp: v.string() },
  handler: async (ctx, { glassesIp }) => {
    return await ctx.db
      .query("pairing_sessions")
      .withIndex("by_ip_status", (q) =>
        q.eq("glassesIp", glassesIp).eq("status", "pending"),
      )
      .collect();
  },
});

export const claimPairingSession = authMutation({
  args: { sessionId: v.string() },
  handler: async (ctx, { sessionId }) => {
    // The wrapper already threw UNAUTHENTICATED if no Clerk identity;
    // ctx.identity is the validated identity for the signed-in caller.
    await rateLimiter.limit(ctx, "pairingClaim", {
      key: ctx.identity.subject,
      throws: true,
    });

    const session = await ctx.db
      .query("pairing_sessions")
      .withIndex("by_session", (q) => q.eq("sessionId", sessionId))
      .unique();
    if (!session) throw new ConvexError({ code: "PAIRING_SESSION_NOT_FOUND" });

    await ctx.db.patch(session._id, {
      status: "claimed",
      clerkUserId: ctx.identity.subject,
      claimingLabel:
        ctx.identity.name ?? ctx.identity.email ?? "your account",
    });
  },
});

// glasses side, after the wearer taps Yes
await confirmPairingSession({ sessionId });
// status flips to "ready"; watchPairingSession now returns the ticket
const ticket = /* read from the confirmed session */;
if (isSignedIn) await signOut();        // stale-session: new ticket wins
await signIn.create({ strategy: "ticket", ticket });
await setActive({ session: signIn.createdSessionId });

The code fallback (different networks)

The same-network path can't link a phone on cellular to glasses on Wi-Fi; there's no shared egress IP for pendingSessionsForIp to match on. The code fallback covers that case. Every pairing session already carries the data it needs: alongside the secret sessionId, createPairingSession now also generates a short code (6 chars, e.g. DQFWT1) and a 2-digit verify number (e.g. 44), both stored on the pairing_sessions row.

export const previewByCode = authMutation({
  args: { code: v.string() },
  handler: async (ctx, { code }): Promise<{ verifyCode: string }> => {
    // ctx.identity is the validated signed-in caller.
    await rateLimiter.limit(ctx, "pairingCodeAttempt", {
      key: ctx.identity.subject,
      throws: true,
    });

    const session = await ctx.db
      .query("pairing_sessions")
      .withIndex("by_code", (q) => q.eq("code", normalizePairingCode(code)))
      .unique();
    if (!session) throw new ConvexError({ code: "NOT_FOUND" });
    return { verifyCode: session.verifyCode };
  },
});

export const confirmByCode = authMutation({
  args: { code: v.string() },
  handler: async (ctx, { code }) => {
    // ctx.identity is the validated signed-in caller.
    await rateLimiter.limit(ctx, "pairingCodeAttempt", {
      key: ctx.identity.subject,
      throws: true,
    });

    const session = await ctx.db
      .query("pairing_sessions")
      .withIndex("by_code", (q) => q.eq("code", normalizePairingCode(code)))
      .unique();
    if (!session) throw new ConvexError({ code: "NOT_FOUND" });

    // claim + confirm in one step: status → "confirmed", skipping "claimed"
    await ctx.db.patch(session._id, {
      status: "confirmed",
      clerkUserId: ctx.identity.subject,
      claimingLabel:
        ctx.identity.name ?? ctx.identity.email ?? "your account",
    });
    // schedule the same mintAndAttach the same-network path uses
    await ctx.scheduler.runAfter(0, internal.pairing.mintAndAttach, {
      sessionId: session.sessionId,
    });
  },
});

Why the verify-match (security)

The code path is the classic device-flow phishing surface. Because the user types a code that they obtained, an attacker could try to trick a signed-in victim into typing the attacker's code, which would sign the attacker's glasses into the victim's account. The 2-digit verify-match defeats this: the number the companion shows is bound to the entered code, so it only matches the glasses the user is actually wearing. An attacker's code shows a different number, and a careful user declines. This is the Bluetooth / WhatsApp-style "confirm the numbers match" pattern.

A few properties make this safe:

• The mint happens only after "Yes, that's mine." That tap is authenticated as the phone user and rate-limited (pairingCodeAttempt), so a guessed or harvested code never produces a credential on its own.
• Consent lives on the phone, by the verify-match. Unlike the same-network path, where consent is the on-glasses "Pair with X?", the code path's consent is the user confirming the number matches the Display they're wearing.
• The session goes straight to confirmed, never claimed. So the glasses never render a Yes/No that someone holding them could press; the only decision is the verify-match on the phone.

Customizing

Change the session expiry

In packages/backend/convex/pairing.ts:

const SESSION_EXPIRES_SECONDS = 120; // 2 min to claim + confirm

Shorten for paranoid scenarios (loaner devices in a public space, in-person handoff at events). Lengthen if your users are slow to reach for their phone after tapping Start Pairing. The default 2-minute window covers the "tap Start, grab your phone, tap your Display, tap Yes" flow with comfortable headroom.

Different rate limits

Three buckets in packages/backend/convex/rateLimiter.ts, all consumed inline via rateLimiter.limit(ctx, "<bucket>", …):

pairingRegister:    { kind: "token bucket", rate: 30, period: HOUR, capacity: 10 },
pairingClaim:       { kind: "token bucket", rate: 30, period: HOUR, capacity: 10 },
pairingCodeAttempt: { kind: "token bucket", rate: 30, period: HOUR, capacity: 10 },

• pairingRegister (keyed per egress IP) caps how many pending sessions a single network can open. Increase only for genuinely busy shared networks (a co-working space full of testers).
• pairingClaim (keyed per user) caps how often one signed-in account can claim Displays. The default leaves plenty of headroom for retries while bounding abuse from a compromised companion session.
• pairingCodeAttempt (keyed per user) caps previewByCode / confirmByCode attempts on the code fallback, so a signed-in account can't grind through codes. Keep this tight; the code space is small enough that the rate limit is part of what makes guessing impractical.

Skip pairing for a specific route

<PairingGate> wraps <App> in app/src/main.tsx. If you have public-facing glasses screens that should be reachable without auth (a kiosk demo, a public weather view), branch above the gate:

const isPublicRoute = window.location.pathname.startsWith("/public");
return (
  <ClerkProvider publishableKey={env.VITE_CLERK_PUBLISHABLE_KEY}>
    <GlassViewport>
      {isPublicRoute ? <PublicApp /> : <PairingGate><App /></PairingGate>}
    </GlassViewport>
  </ClerkProvider>
);

<GlassViewport> stays as the outermost UI wrapper so both branches are bounded inside the 600×600 surface.

The companion's CORS allowlist

POST /api/pair/register only accepts cross-origin calls from your deployed glasses app. The allowed origin is GLASSES_APP_URL (the same env var the deploy guide covers). If you serve the glasses app from a new domain, update GLASSES_APP_URL so the register route keeps accepting its requests. See Deploy.

Local dev

The local-pairing options in Quickstart §5 all preserve the same flow:

• Browser preview: localhost:5173 shares the Clerk session with localhost:3000 because both apps point at the same Convex URL + Clerk publishable key. The cookie is already there, so you rarely need to pair at all.
• Exercising the real pairing flow locally: tap Start Pairing in the glasses app, then open /pair on the same machine. Both surfaces share the same egress IP (localhost), so the Display shows up on /pair immediately; tap it, then approve on the glasses.

The full same-network flow only matters in production, where your user's phone is a different device from the glasses but sits on the same Wi-Fi. Locally, both surfaces share one egress IP, so discovery just works.

Debugging

Why not magic-link, OAuth, password, or a QR?

• Magic-link: requires the user to type an email/code on a D-pad. Same UX problem we're solving.
• OAuth redirect: would work, but requires the glasses app to open a system browser (Meta AI app doesn't), then redirect back. Sign-In Tokens skip the browser hop entirely.
• Password: D-pad. No.
• A scannable QR on the dashboard: the Display has no camera, so it can't scan one; and rendering a QR on the Display for the phone to scan fights the near-eye optics. Same-network discovery needs no optics on either side.
• A typed short code: miserable on arrow-keys-only input, and unnecessary: the on-glasses Yes already gives the wearer the final say, so there's no secret to type.

Same-network discovery + on-glasses approval is the shape that fits a cameraless, keyboardless, single-wearer HUD: the wearer's two devices find each other over the network they already share, and the wearer confirms with one tap. The Clerk Sign-In Token stays the underlying primitive, minted only after that tap, never on a URL.