Server-Side Token Verification Example with SocketFi

Client-side authentication proves to your frontend that a user is who they claim to be — but your backend needs its own proof before serving sensitive data or executing business logic. Every protected API call should include the socketfiAccessToken in an Authorization: Bearer header, and every protected route should call verifyAuth() before trusting any user-supplied data. This example gives you a production-ready Express server with centralized middleware, full TypeScript types, and several protected route patterns to copy from.

Architecture

React app authenticates  →  receives { socketfiAccessToken, userProfile }
       ↓
Frontend attaches token: Authorization: Bearer <token>
       ↓
Express receives request
       ↓
authMiddleware calls verifyAuth(token)
       ↓
{ valid: true, user: { id }, wallet: "CDXXX…" } attached to req.user
       ↓
Route handler executes business logic with verified identity

Installation

npm install @socketfi/server express
npm install --save-dev @types/express typescript

Project structure

src/
├── middleware/
│   └── auth.ts           # verifyAuth() middleware
├── routes/
│   ├── profile.ts        # Protected user profile route
│   └── wallet.ts         # Protected wallet info route
├── types/
│   └── express.d.ts      # Extend Express Request with req.user
├── app.ts                # Express app setup
└── server.ts             # HTTP server entry point

Step-by-step files

Starting the server

src/server.ts

import app from "./app";

const PORT = process.env.PORT ?? 3000;

app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
});

Calling protected endpoints from the frontend

Attach the access token from the authenticated session to every request:

import { useAuth } from "../auth/useAuth";

function useApi() {
  const { session } = useAuth();

  const get = async (path: string) => {
    const res = await fetch(path, {
      headers: {
        Authorization: `Bearer ${session?.socketfiAccessToken}`,
        "Content-Type": "application/json",
      },
    });
    if (!res.ok) throw new Error(`API error ${res.status}`);
    return res.json();
  };

  return { get };
}

Verification result shape

verifyAuth() returns:

interface VerifyResult {
  valid: boolean;
  user: { id: string };
  wallet: string;
}

Use result.wallet — not any wallet address sent in the request body — as the authoritative identity for all business logic.

Ownership validation pattern

A common pattern: ensure the caller is acting on their own resources, not someone else’s.

router.delete("/positions/:positionId", async (req, res) => {
  const position = await db.positions.findById(req.params.positionId);

  if (!position) {
    return res.status(404).json({ message: "Not found." });
  }

  // Only the wallet that owns this position may delete it
  if (position.wallet !== req.user!.wallet) {
    return res.status(403).json({ message: "Forbidden." });
  }

  await db.positions.delete(req.params.positionId);
  return res.json({ deleted: true });
});

Applying middleware per-route instead of globally

If your app has a mix of public and private endpoints, apply authMiddleware at the route level:

import { authMiddleware } from "./middleware/auth";

// Public
app.get("/api/public-data", publicHandler);

// Private
app.get("/api/profile", authMiddleware, profileHandler);
app.get("/api/wallet", authMiddleware, walletHandler);
app.post("/api/transaction", authMiddleware, transactionHandler);

Using with Fastify, NestJS, or Hono

verifyAuth() is framework-agnostic — the same function works wherever you can extract a Bearer token from a request header.

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

const app = Fastify();

app.addHook("preHandler", async (request, reply) => {
  const token = request.headers.authorization?.replace("Bearer ", "");
  if (!token) return reply.status(401).send({ message: "Unauthorized." });

  const result = await verifyAuth(token);
  if (!result.valid) return reply.status(401).send({ message: "Unauthorized." });

  (request as any).user = { id: result.user.id, wallet: result.wallet };
});

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

const app = new Hono();

app.use("/api/*", async (c, next) => {
  const token = c.req.header("Authorization")?.replace("Bearer ", "");
  if (!token) return c.json({ message: "Unauthorized." }, 401);

  const result = await verifyAuth(token);
  if (!result.valid) return c.json({ message: "Unauthorized." }, 401);

  c.set("user", { id: result.user.id, wallet: result.wallet });
  await next();
});

Clearing the key cache during testing

@socketfi/server caches public keys internally to reduce network round-trips on every verifyAuth() call. In automated tests and CI environments, you can call clearKeyCache() to flush the cache and force fresh key retrieval — useful when rotating keys between test runs.

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

// Call this in a beforeEach / afterAll hook when testing token verification
clearKeyCache();

clearKeyCache() is intended for testing environments. You do not need to call it in production code — the cache refreshes automatically.

Security checklist

Always call verifyAuth()

Every protected endpoint must verify the token server-side. Never trust wallet addresses or user IDs sent from the client.

Use HTTPS

Bearer tokens in transit must be protected by TLS. HTTPS is required in production.

Validate ownership

After verifying identity, confirm the user owns the resource they’re accessing before executing any write operation.

Never log tokens

Access tokens are credentials. Log error messages, not token values.

Integration Guides

Recovery & Rotation

Examples

Resources

Server-Side Token Verification Example with SocketFi

Architecture

Installation

Project structure

Step-by-step files

Starting the server

Calling protected endpoints from the frontend

Verification result shape

Ownership validation pattern

Applying middleware per-route instead of globally

Using with Fastify, NestJS, or Hono

Clearing the key cache during testing

Security checklist

Always call verifyAuth()

Use HTTPS

Validate ownership

Never log tokens

​Architecture

​Installation

​Project structure

​Step-by-step files

​Starting the server

​Calling protected endpoints from the frontend

​Verification result shape

​Ownership validation pattern

​Applying middleware per-route instead of globally

​Using with Fastify, NestJS, or Hono

​Clearing the key cache during testing

​Security checklist

Always call verifyAuth()

Use HTTPS

Validate ownership

Never log tokens

Architecture

Installation

Project structure

Step-by-step files

Starting the server

Calling protected endpoints from the frontend

Verification result shape

Ownership validation pattern

Applying middleware per-route instead of globally

Using with Fastify, NestJS, or Hono

Clearing the key cache during testing

Security checklist