Authenticate Users with SocketFi Passkey Authentication

Authentication is the gateway to every SocketFi capability. Before a user can view their wallet, request a transaction, or interact with any on-chain contract, they must first authenticate. SocketFi handles this through a hosted, passwordless flow built on passkeys — the same FIDO2 standard used by Apple, Google, and Microsoft. A single authenticate() call covers both new user registration and returning user sign-in; the SDK detects which flow to run automatically. This guide covers the full authentication lifecycle: passkey registration vs. sign-in, session storage, backend token verification, protected routes, session expiration, re-authentication, and logout.

How authentication works

When you call socketfi.authenticate(), the SDK opens the SocketFi hosted authentication flow. For a new user, the flow creates a passkey on their device and provisions a smart wallet on Stellar. For a returning user, the flow prompts for their existing passkey and creates a fresh session. In both cases, your app receives a Session object containing an access token and wallet information.

User calls authenticate()
        ↓
SocketFi hosted flow opens
        ↓
Passkey prompt (device biometrics / security key)
        ↓
Session returned to your app
        ↓
User accesses wallet

Authentication proves identity — it does not authorize individual transactions. Every state-changing contract call goes through a separate approval step when you call requestTransaction().

Calling authenticate()

The call signature is the same for both registration and sign-in:

const session = await socketfi.authenticate();

The returned Session object looks like this:

type Session = {
  socketfiAccessToken: string; // JWT — verify this server-side
  userProfile: {
    id: string;          // SocketFi user identifier
    wallet: string;      // Stellar smart wallet address (e.g. "CDXX…")
  };
};

Session storage and management

After authentication succeeds, persist the session so users stay logged in across page reloads or app restarts.

React (web)
React Native

Store the session in localStorage and rehydrate it on mount:

src/auth/provider.tsx

import { useState, useEffect, useCallback, ReactNode } from "react";
import { socketfi } from "../socketfi/client";
import { AuthContext, Session } from "./context";

const SESSION_KEY = "socketfi_session";

export function AuthProvider({ children }: { children: ReactNode }) {
  const [loading, setLoading] = useState(true);
  const [session, setSession] = useState<Session | null>(null);

  useEffect(() => {
    const stored = localStorage.getItem(SESSION_KEY);
    if (stored) {
      try {
        setSession(JSON.parse(stored));
      } catch {
        localStorage.removeItem(SESSION_KEY);
      }
    }
    setLoading(false);
  }, []);

  const login = useCallback(async () => {
    setLoading(true);
    try {
      const result = await socketfi.authenticate();
      setSession(result as Session);
      localStorage.setItem(SESSION_KEY, JSON.stringify(result));
    } finally {
      setLoading(false);
    }
  }, []);

  const logout = useCallback(() => {
    setSession(null);
    localStorage.removeItem(SESSION_KEY);
  }, []);

  return (
    <AuthContext.Provider
      value={{ loading, authenticated: !!session, session, login, logout }}
    >
      {children}
    </AuthContext.Provider>
  );
}

Use expo-secure-store — it encrypts data in the device keychain, unlike AsyncStorage which stores data in plain text.

src/auth/provider.tsx

import { useState, useEffect, useCallback, ReactNode } from "react";
import * as SecureStore from "expo-secure-store";
import { socketfi } from "../socketfi/client";
import { AuthContext, Session } from "./context";

const SESSION_KEY = "socketfi_session";

export function AuthProvider({ children }: { children: ReactNode }) {
  const [loading, setLoading] = useState(true);
  const [session, setSession] = useState<Session | null>(null);

  useEffect(() => {
    SecureStore.getItemAsync(SESSION_KEY).then((stored) => {
      if (stored) {
        try { setSession(JSON.parse(stored)); }
        catch { SecureStore.deleteItemAsync(SESSION_KEY); }
      }
      setLoading(false);
    });
  }, []);

  const login = useCallback(async () => {
    setLoading(true);
    try {
      const result = await socketfi.authenticate();
      setSession(result as Session);
      await SecureStore.setItemAsync(SESSION_KEY, JSON.stringify(result));
    } finally {
      setLoading(false);
    }
  }, []);

  const logout = useCallback(async () => {
    setSession(null);
    await SecureStore.deleteItemAsync(SESSION_KEY);
  }, []);

  return (
    <AuthContext.Provider
      value={{ loading, authenticated: !!session, session, login, logout }}
    >
      {children}
    </AuthContext.Provider>
  );
}

Backend token verification

Never rely on client-side session state to grant access to backend resources. Always verify socketfiAccessToken server-side using the @socketfi/server package.

npm install @socketfi/server

The verifyAuth() function validates the token signature and returns the verified user and wallet:

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

const result = await verifyAuth(token);
// result.valid         → boolean
// result.user.id       → SocketFi user identifier
// result.wallet.address → Stellar wallet address

Express middleware example

src/server/middleware/requireAuth.ts

import { Request, Response, NextFunction } from "express";
import { verifyAuth } from "@socketfi/server";

export async function requireAuth(
  req: Request,
  res: Response,
  next: NextFunction
) {
  const header = req.headers.authorization;
  if (!header?.startsWith("Bearer ")) {
    return res.status(401).json({ error: "Missing authorization header" });
  }

  const token = header.slice(7);

  try {
    const result = await verifyAuth(token);

    if (!result.valid) {
      return res.status(401).json({ error: "Invalid or expired token" });
    }

    // Attach verified identity so downstream handlers can use it safely
    (req as any).socketfi = {
      userId: result.user.id,
      walletAddress: result.wallet.address,
    };

    next();
  } catch {
    return res.status(401).json({ error: "Token verification failed" });
  }
}

Apply it to protected routes:

src/server/routes/wallet.ts

import { Router } from "express";
import { requireAuth } from "../middleware/requireAuth";

const router = Router();

router.get("/balance", requireAuth, async (req, res) => {
  const { walletAddress } = (req as any).socketfi;
  // fetch balance for walletAddress …
  res.json({ walletAddress, balance: "1000" });
});

export default router;

Protected routes

React (web)

Wrap sensitive routes in a guard component that redirects unauthenticated users to your login page:

src/components/ProtectedRoute.tsx

import { Navigate } from "react-router-dom";
import { useAuth } from "../auth/context";
import { ReactNode } from "react";

export function ProtectedRoute({ children }: { children: ReactNode }) {
  const { loading, authenticated } = useAuth();

  if (loading) {
    return (
      <div style={{ display: "flex", justifyContent: "center", padding: 48 }}>
        <span>Loading…</span>
      </div>
    );
  }

  if (!authenticated) {
    return <Navigate to="/login" replace />;
  }

  return <>{children}</>;
}

React Native

Use a navigator that conditionally renders the authenticated or unauthenticated stack:

src/navigation/RootNavigator.tsx

import { useAuth } from "../auth/context";
import { AuthStack } from "./AuthStack";
import { AppStack } from "./AppStack";

export function RootNavigator() {
  const { loading, authenticated } = useAuth();

  if (loading) return null; // or a splash screen

  return authenticated ? <AppStack /> : <AuthStack />;
}

Handling session expiration and re-authentication

Sessions expire after a period of inactivity. When an API call returns 401, catch it and trigger re-authentication:

src/api/client.ts

import { socketfi } from "../socketfi/client";

export async function authenticatedFetch(
  url: string,
  options?: RequestInit
): Promise<Response> {
  const token = getStoredToken(); // read from your session store

  const res = await fetch(url, {
    ...options,
    headers: {
      ...options?.headers,
      Authorization: `Bearer ${token}`,
    },
  });

  if (res.status === 401) {
    // Session expired — re-authenticate transparently
    const session = await socketfi.authenticate();
    storeSession(session); // persist the refreshed session

    // Retry the original request with the new token
    return fetch(url, {
      ...options,
      headers: {
        ...options?.headers,
        Authorization: `Bearer ${session.socketfiAccessToken}`,
      },
    });
  }

  return res;
}

Logout

Logout removes the local session state. It does not delete the user’s wallet, revoke the passkey, or affect any on-chain assets.

React (web)
React Native

const logout = () => {
  setSession(null);
  localStorage.removeItem("socketfi_session");
};

const logout = async () => {
  setSession(null);
  await SecureStore.deleteItemAsync("socketfi_session");
};

After logout, redirect the user to your login screen and reset any component state that depends on the session.

Error handling for auth failures

Wrap every authenticate() call in try/catch. The most common errors are:

Error code	Cause	Recommended response
`USER_CANCELLED`	User dismissed the passkey prompt	Show a gentle retry message
`POPUP_BLOCKED`	Browser blocked the SocketFi popup	Advise the user to allow popups for your domain
`INVALID_CLIENT_ID`	The `clientId` passed to `new SocketFi()` is wrong or missing	Check your environment variable and Dashboard project
Passkey rejected	Biometric check failed	Ask the user to try again
Authentication failed	Network or server issue	Show an error with a retry button
Credential missing	Passkey deleted from device	Prompt the user to start account recovery

const handleLogin = async () => {
  setLoading(true);
  setError(null);
  try {
    await login();
  } catch (err: unknown) {
    if (err instanceof Error) {
      if (err.message === "USER_CANCELLED") {
        // User dismissed — don't show an alarming error
        setError("Sign-in cancelled. Tap the button to try again.");
      } else if (err.message === "POPUP_BLOCKED") {
        setError("Sign-in popup was blocked. Please allow popups for this site and try again.");
      } else if (err.message === "INVALID_CLIENT_ID") {
        setError("Configuration error. Please contact support.");
      } else {
        setError("Sign-in failed. Please try again.");
      }
    }
  } finally {
    setLoading(false);
  }
};

You can also configure a global error handler on the client instance to capture all SDK errors in one place:

src/socketfi/client.ts

import { SocketFi } from "@socketfi/react";

export const socketfi = new SocketFi({
  clientId: import.meta.env.VITE_SOCKETFI_CLIENT_ID,
  network: "TESTNET",
  onError(error) {
    // Send to Sentry, Datadog, or your error tracking tool
    reportError(error);
  },
});

Production checklist

✅ Verify socketfiAccessToken server-side with @socketfi/server before granting API access
✅ Store tokens in encrypted storage (expo-secure-store on mobile, sessionStorage for stricter web security)
✅ Handle session expiration and re-authenticate transparently
✅ Protect all sensitive routes with an auth guard
✅ Show loading indicators during the passkey prompt and session restore
✅ Monitor authentication failures in your observability tool

Integration Guides

Recovery & Rotation

Examples

Resources

Authenticate Users with SocketFi Passkey Authentication

How authentication works

Calling authenticate()

Session storage and management

Backend token verification

Express middleware example

Protected routes

React (web)

React Native

Handling session expiration and re-authentication

Logout

Error handling for auth failures

Production checklist

​How authentication works

​Calling authenticate()

​Session storage and management

​Backend token verification

​Express middleware example

​Protected routes

​React (web)

​React Native

​Handling session expiration and re-authentication

​Logout

​Error handling for auth failures

​Production checklist

How authentication works

Calling authenticate()

Session storage and management

Backend token verification

Express middleware example

Protected routes

React (web)

React Native

Handling session expiration and re-authentication

Logout

Error handling for auth failures

Production checklist