SocketFi Server SDK — Backend Token Verification

The @socketfi/server SDK gives your backend a single, reliable way to confirm that a request comes from a user who has already authenticated through SocketFi. It never performs authentication itself — that responsibility belongs to the client SDK. Your server’s only job is to verify the signed token that the client forwards, extract the user and wallet information embedded in it, and decide whether to fulfil the request.

Installation

Install the package with your preferred package manager:

npm install @socketfi/server

yarn add @socketfi/server

pnpm add @socketfi/server

Requirements

Requirement	Minimum
Node.js	20+
Module system	ESM or TypeScript

Supported frameworks and runtimes include Express, Fastify, NestJS, and Serverless Functions (AWS Lambda, Vercel, Cloudflare Workers, etc.).

Key principle: verify, don’t authenticate

SocketFi follows a clean separation of concerns. The client SDK handles the full passkey authentication flow and receives a signed access token from SocketFi’s servers. Your backend then calls verifyAuth() to cryptographically confirm that token is genuine before granting access to any protected resource. Never trust authentication state that originates on the client. Always verify the token on every protected request.

Quick start

Import verifyAuth and call it with the token extracted from the Authorization header:

import express from 'express';
import { verifyAuth } from '@socketfi/server';

const app = express();

app.get('/profile', async (req, res) => {
  const token = req.headers.authorization?.replace('Bearer ', '');

  if (!token) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const auth = await verifyAuth(token);

  if (!auth.valid) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  return res.json({
    user: auth.user,
    wallet: auth.wallet,
  });
});

app.listen(3000);

A successful call to verifyAuth() returns the verified user ID and the user’s Stellar wallet address — everything you need to authorize the request and associate it with the right account.

How token verification works

The SDK handles all cryptographic complexity automatically:

Downloads signing keys — fetches SocketFi’s public JWKS endpoint on first use.
Verifies the signature — confirms the token was signed by SocketFi and has not been tampered with.
Validates claims — checks expiry, issuer, and audience fields.
Returns a trusted result — your code receives a plain, typed object with no raw JWT handling required.

Signing keys are cached in memory after the first download to reduce latency and eliminate redundant network requests. You can clear the cache at any time by calling clearKeyCache() — useful during development or key-rotation testing.

When to use the Server SDK

Use verifyAuth() on every route or handler that requires a logged-in user. Typical use cases include:

Reading or writing user-specific data
Initiating blockchain transactions on behalf of a user
Associating a wallet address with a database record
Enforcing per-user authorization rules after confirming identity

Authentication confirms who the user is. Authorization — deciding what they are allowed to do — is your application’s responsibility. After verifyAuth() succeeds, apply any additional permission checks your business logic requires.

Available exports

import { verifyAuth, clearKeyCache } from '@socketfi/server';

Export	Type	Description
`verifyAuth`	`(token: string) => Promise<VerifyAuthResult>`	Verifies a SocketFi access token and returns user and wallet info.
`clearKeyCache`	`() => void`	Clears the in-memory JWKS key cache. Intended for development and testing only.

Clearing the key cache

clearKeyCache() wipes the in-memory JWKS signing-key cache so that the next verifyAuth() call re-fetches fresh keys from SocketFi. Most production applications never need this — the SDK manages key caching automatically. Call it only in specific scenarios:

Local development — force a key refresh without restarting the server.
Integration tests — reset key state between test runs to ensure isolation.
Key-rotation drills — validate that your server picks up rotated keys correctly.

import { clearKeyCache, verifyAuth } from '@socketfi/server';

// Force a fresh key download before the next verification —
// useful in test setup or after a manual key rotation.
clearKeyCache();

const auth = await verifyAuth(token);

Do not call clearKeyCache() on every request. Clearing the cache triggers a network round-trip to re-fetch the JWKS on the next verifyAuth() call, which adds latency. Reserve it for development, testing, and key-rotation workflows only.

Authentication flow

React / Mobile App
       ↓
  SocketFi Client SDK  →  Passkey authentication
       ↓
  Access Token Issued
       ↓
  API Request  (Authorization: Bearer <token>)
       ↓
  verifyAuth()  ←  @socketfi/server
       ↓
  Protected Resource

React SDK

React Native SDK

Server SDK

API Reference

SocketFi Server SDK — Backend Token Verification

Installation

Requirements

Key principle: verify, don’t authenticate

Quick start

How token verification works

When to use the Server SDK

Available exports

Clearing the key cache

Authentication flow

​Installation

​Requirements

​Key principle: verify, don’t authenticate

​Quick start

​How token verification works

​When to use the Server SDK

​Available exports

​Clearing the key cache

​Authentication flow

Installation

Requirements

Key principle: verify, don’t authenticate

Quick start

How token verification works

When to use the Server SDK

Available exports

Clearing the key cache

Authentication flow