React Authentication Example with SocketFi Passkeys

Building authentication with SocketFi means your users get a passkey-powered, seed-phrase-free login experience, and you get a fully typed session object with a wallet address and an access token ready to send to your backend. This example walks you through every file you need — from SDK initialization to protected routes — so you can drop a working auth system into any React project.

Project structure

Your authentication module lives under src/auth/. Keep the SocketFi client in its own file so it’s instantiated exactly once and imported wherever you need it.

src/
├── socketfi/
│   └── client.ts          # SDK singleton
├── auth/
│   ├── AuthContext.tsx    # Context shape + createContext
│   ├── AuthProvider.tsx   # State, login, logout, session restore
│   └── useAuth.ts         # Convenience hook
├── routes/
│   └── ProtectedRoute.tsx # Route guard
└── pages/
    └── LoginPage.tsx      # Login button component

Installation

npm install @socketfi/react

Set your client ID in an environment variable — never hard-code it.

# .env
VITE_SOCKETFI_CLIENT_ID=your_client_id_here

Step-by-step files

Wire everything together

Wrap your app in <AuthProvider> at the root so every component can call useAuth().

src/main.tsx

import React from "react";
import ReactDOM from "react-dom/client";
import { AuthProvider } from "./auth/AuthProvider";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <AuthProvider>
      <App />
    </AuthProvider>
  </React.StrictMode>
);

src/App.tsx

import { BrowserRouter, Routes, Route } from "react-router-dom";
import LoginPage from "./pages/LoginPage";
import DashboardPage from "./pages/DashboardPage";
import { ProtectedRoute } from "./routes/ProtectedRoute";

export default function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/login" element={<LoginPage />} />
        <Route
          path="/"
          element={
            <ProtectedRoute>
              <DashboardPage />
            </ProtectedRoute>
          }
        />
      </Routes>
    </BrowserRouter>
  );
}

Authentication flow

User clicks "Continue with passkey"
       ↓
socketfi.authenticate() opens the hosted flow
       ↓
User approves with Face ID / Touch ID / Windows Hello
       ↓
SocketFi returns AuthSession { socketfiAccessToken, userProfile }
       ↓
Session stored in localStorage
       ↓
User redirected to protected route

Session persistence flow

App starts
       ↓
AuthProvider mounts → reads localStorage
       ↓
Existing session found → setSession(parsed)
       ↓
User is immediately authenticated (no second login prompt)

Accessing wallet info

After authentication, the wallet address is available anywhere inside <AuthProvider>:

const { session } = useAuth();
const walletAddress = session?.userProfile?.wallet;

Sending the token to your backend

Attach socketfiAccessToken as a Bearer token on every authenticated API request:

const { session } = useAuth();

const response = await fetch("/api/me", {
  headers: {
    Authorization: `Bearer ${session?.socketfiAccessToken}`,
  },
});

Backend token verification

Your Express (or other) server verifies the token with @socketfi/server before trusting any request. See the Server Verification example for a complete implementation.

import { verifyAuth } from "@socketfi/server";

const result = await verifyAuth(accessToken);
// result.valid, result.user, result.wallet

Never trust wallet addresses or user IDs sent directly from the client. Always verify the access token server-side with verifyAuth() and derive identity from the verified result.

Logout flow

User clicks "Logout"
       ↓
localStorage.removeItem("socketfi_session")
       ↓
setSession(null)
       ↓
ProtectedRoute redirects to /login

Logout only clears local session state — the user’s wallet and assets are completely unaffected.

Production checklist

Session security

Store sessions in localStorage for web or secure device storage for mobile. Never store tokens in memory-only state.

Error handling

Catch USER_CANCELLED separately and don’t show it as an error. All other failures should surface a retry prompt.

Token verification

Every protected backend endpoint must call verifyAuth() — never rely on client-provided identity claims.

HTTPS

WebAuthn / passkeys require a secure context. HTTPS is mandatory in production.

Integration Guides

Recovery & Rotation

Examples

Resources

React Authentication Example with SocketFi Passkeys

Project structure

Installation

Step-by-step files

Wire everything together

Authentication flow

Session persistence flow

Accessing wallet info

Sending the token to your backend

Backend token verification

Logout flow

Production checklist

Session security

Error handling

Token verification

HTTPS

​Project structure

​Installation

​Step-by-step files

​Wire everything together

​Authentication flow

​Session persistence flow

​Accessing wallet info

​Sending the token to your backend

​Backend token verification

​Logout flow

​Production checklist

Session security

Error handling

Token verification

HTTPS

Project structure

Installation

Step-by-step files

Wire everything together

Authentication flow

Session persistence flow

Accessing wallet info

Sending the token to your backend

Backend token verification

Logout flow

Production checklist