Session Management — SocketFi Access Tokens & Storage

Every time a user successfully authenticates, SocketFi creates a session — a short-lived proof of identity that your application uses to identify the user and authorize requests to your backend. Sessions are separate from the wallet itself: a session can expire or be cleared without affecting the wallet, its balances, or any on-chain state. Understanding sessions is essential for building a secure, responsive application on top of SocketFi.

What Is a Session?

A session represents a recently verified user. It contains two pieces of information:

interface Session {
  userProfile: {
    id: string;         // Stable, permanent user identifier
    username?: string;  // User's display name, if set
  };
  socketfiAccessToken: string; // Signed JWT — your proof of authentication
}

The socketfiAccessToken is a signed JSON Web Token (JWT). It encodes the user’s identity and wallet association, and it is cryptographically signed by SocketFi so your backend can verify it without making an additional network call to SocketFi’s servers.

Using the Access Token

Attach the access token to every request your application makes to your own backend. Use the standard Authorization: Bearer header:

const session = await socketfi.authenticate();

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

Your backend receives this header, verifies the token with @socketfi/server, and extracts the user identity and wallet address. See Backend Verification for the complete server-side flow.

Never use the socketfiAccessToken as a primary key or store it as a user identifier. Use session.userProfile.id as your stable foreign key. The access token changes every time the user re-authenticates.

Session Storage

Where you store the session depends on your platform.

React (Web)
React Native

For web applications, localStorage works well for persisting the token across page reloads. Pair it with React state for in-memory access during the session.

// After authentication
const session = await socketfi.authenticate();
localStorage.setItem("socketfi_token", session.socketfiAccessToken);

// On app startup — restore from storage
const storedToken = localStorage.getItem("socketfi_token");

// On logout — clear everything
localStorage.removeItem("socketfi_token");

localStorage is accessible to JavaScript on the same origin. If your application has a Content Security Policy and is not susceptible to XSS, this is an acceptable trade-off for usability. For higher-security applications, consider storing the token in an httpOnly cookie set by your own backend.

Use AsyncStorage for simple persistence or expo-secure-store for hardware-backed encrypted storage (recommended for production).

import AsyncStorage from "@react-native-async-storage/async-storage";

// Store after authentication
await AsyncStorage.setItem("socketfi_token", session.socketfiAccessToken);

// Restore on app launch
const token = await AsyncStorage.getItem("socketfi_token");

// Clear on logout
await AsyncStorage.removeItem("socketfi_token");

import * as SecureStore from "expo-secure-store";

// Encrypted storage (recommended for production)
await SecureStore.setItemAsync("socketfi_token", session.socketfiAccessToken);
const token = await SecureStore.getItemAsync("socketfi_token");
await SecureStore.deleteItemAsync("socketfi_token");

React Context Example

For most React applications, a Context provider is the cleanest way to share session state across your component tree.

import React, { createContext, useContext, useState, useEffect } from "react";
import { socketfi } from "./socketfi"; // Your initialized SocketFi instance

interface SessionContextValue {
  user: { id: string; username?: string } | null;
  token: string | null;
  signIn: () => Promise<void>;
  signOut: () => void;
}

const SessionContext = createContext<SessionContextValue | null>(null);

export function SessionProvider({ children }: { children: React.ReactNode }) {
  const [user, setUser] = useState<{ id: string; username?: string } | null>(null);
  const [token, setToken] = useState<string | null>(null);

  // Restore session from storage on mount
  useEffect(() => {
    const storedToken = localStorage.getItem("socketfi_token");
    const storedUser = localStorage.getItem("socketfi_user");
    if (storedToken && storedUser) {
      setToken(storedToken);
      setUser(JSON.parse(storedUser));
    }
  }, []);

  async function signIn() {
    const session = await socketfi.authenticate();
    setUser(session.userProfile);
    setToken(session.socketfiAccessToken);
    localStorage.setItem("socketfi_token", session.socketfiAccessToken);
    localStorage.setItem("socketfi_user", JSON.stringify(session.userProfile));
  }

  function signOut() {
    setUser(null);
    setToken(null);
    localStorage.removeItem("socketfi_token");
    localStorage.removeItem("socketfi_user");
  }

  return (
    <SessionContext.Provider value={{ user, token, signIn, signOut }}>
      {children}
    </SessionContext.Provider>
  );
}

export function useSession() {
  const ctx = useContext(SessionContext);
  if (!ctx) throw new Error("useSession must be used within SessionProvider");
  return ctx;
}

Use it in your components:

function Dashboard() {
  const { user, token, signOut } = useSession();

  return (
    <div>
      <p>Welcome, {user?.username}</p>
      <button onClick={signOut}>Sign Out</button>
    </div>
  );
}

Session Expiration

Sessions are intentionally short-lived. When a socketfiAccessToken expires, your backend will return an HTTP 401 response to requests that include it. Design your application to handle this without disrupting the user experience:

async function authorizedFetch(url: string, options: RequestInit = {}) {
  const { token, signIn } = useSessionStore(); // however you access your token

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

  if (response.status === 401) {
    // Prompt re-authentication and retry
    await signIn();
    const freshToken = getToken();
    return fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        Authorization: `Bearer ${freshToken}`,
      },
    });
  }

  return response;
}

Proactively decode the JWT on the client and check the exp claim before making requests. This lets you trigger re-authentication before an API call fails, resulting in a smoother user experience.

Sessions vs. Wallets

It is important to understand that sessions and wallets are completely independent.

Session	Wallet
Temporary — expires	Permanent — persists forever
Cleared on logout	Unchanged by logout
New token on re-auth	Same address on re-auth
Proof of recent login	Proof of on-chain ownership

Session Expires
  ↓
Wallet Still Exists (all assets intact)
  ↓
User Re-authenticates
  ↓
Same Wallet, New Session Token

Signing out does not delete, freeze, or affect the wallet in any way.

Common Session Errors

Error	Cause	Resolution
`Missing Token`	No `Authorization` header was sent	Ensure your fetch wrapper always attaches the stored token
`Invalid Token`	The JWT is malformed or was tampered with	Never modify the raw token string; re-authenticate to get a fresh one
`Expired Token`	The JWT `exp` claim has passed	Call `socketfi.authenticate()` to get a new session
`Invalid Signature`	The token was not signed by SocketFi	Treat this as a security event — do not grant access; alert your monitoring

Security Best Practices

Always verify tokens server-side. Frontend session state tells you who the user claims to be. The verifyAuth() call tells you who they actually are.
Use HTTPS exclusively. Session tokens transmitted over plain HTTP can be intercepted. All production traffic must be encrypted.
Store minimal data. Persist only the token and the user profile. Do not store wallet addresses, balance data, or other wallet state in session storage.
Handle expiration gracefully. Build automatic re-authentication into your data-fetching layer so users are not unexpectedly locked out.

Get Started

Authentication

Embedded Wallets

Transactions

Smart Wallet

Security

Session Management — SocketFi Access Tokens & Storage

What Is a Session?

Using the Access Token

Session Storage

React Context Example

Session Expiration

Sessions vs. Wallets

Common Session Errors

Security Best Practices

​What Is a Session?

​Using the Access Token

​Session Storage

​React Context Example

​Session Expiration

​Sessions vs. Wallets

​Common Session Errors

​Security Best Practices

What Is a Session?

Using the Access Token

Session Storage

React Context Example

Session Expiration

Sessions vs. Wallets

Common Session Errors

Security Best Practices