verifyAuth() — SocketFi Backend Token Verification

verifyAuth() is the core function of the @socketfi/server SDK. Call it on every incoming request that requires authentication, passing the raw token from the Authorization header. The function downloads and caches SocketFi’s public signing keys automatically, verifies the token’s cryptographic signature, validates its claims, and returns a strongly-typed result you can act on immediately — no manual JWT configuration required.

Function signature

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

const result: VerifyAuthResult = await verifyAuth(token: string);

Parameters

string

required

The raw SocketFi access token string. Extract this from the Authorization: Bearer <token> header before passing it to verifyAuth(). Do not include the Bearer prefix.

Return value

verifyAuth() returns Promise<VerifyAuthResult>. The shape of the resolved value depends on whether verification succeeded.

On success

true

required

Always true when verification succeeds.

object

required

The verified user object.

Show user fields

string

required

The unique SocketFi user identifier (e.g. "usr_01hx..."). Use this value as the stable foreign key when storing user data in your database.

object

required

The user’s embedded Stellar smart wallet.

Show wallet fields

string

required

The user’s Stellar/Soroban wallet address (e.g. "GDZX..."). Use this when constructing on-chain operations or looking up balances.

On failure

false

required

Always false when verification fails.

object

required

The verification error.

Show error fields

string

required

A machine-readable error code. See the error codes table below for the full list and recommended handling.

Extracting the token from the Authorization header

SocketFi access tokens are sent as Bearer tokens. Parse them from the Authorization header before calling verifyAuth():

const authHeader = req.headers.authorization;
const token = authHeader?.replace('Bearer ', '');

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

Call verifyAuth() on every protected request. Never cache or reuse the result across requests — each call re-validates the token’s expiry and signature freshness.

Success example

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

const token = req.headers.authorization?.replace('Bearer ', '');
const auth = await verifyAuth(token);

if (auth.valid) {
  console.log(auth);
  // {
  //   valid: true,
  //   user: { id: 'usr_01hx...' },
  //   wallet: { address: 'GDZX...' }
  // }

  // Safe to proceed — user is authenticated
  return res.json({ user: auth.user, wallet: auth.wallet });
}

Failure example

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

const token = req.headers.authorization?.replace('Bearer ', '');
const auth = await verifyAuth(token);

if (!auth.valid) {
  console.log(auth);
  // {
  //   valid: false,
  //   error: { code: 'TOKEN_EXPIRED' }
  // }

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

Complete protected route example

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

const app = express();

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

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

  const auth = await verifyAuth(token);

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

  // auth.user.id and auth.wallet.address are now safe to use
  const userData = await db.users.findOne({ id: auth.user.id });

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

Error codes

The following error codes can appear in auth.error.code when auth.valid is false:

Code	Meaning	How to handle
`TOKEN_REQUIRED`	No token was provided (empty or `undefined` string passed).	Check that the client is sending the `Authorization: Bearer <token>` header.
`INVALID_SIGNATURE`	The token’s cryptographic signature did not pass verification.	Reject the request. The token may have been tampered with or forged.
`TOKEN_EXPIRED`	The token’s expiry claim is in the past.	Return a `401` and prompt the user to re-authenticate via the client SDK.
`INVALID_ISSUER`	The token’s issuer claim does not match SocketFi’s expected value.	Reject the request. The token was not issued by SocketFi.

You do not need to configure signing keys, JWKS URLs, or JWT libraries. verifyAuth() handles all of that automatically. If you need to force-refresh the cached public keys (for example, during key-rotation testing), call clearKeyCache() before the next verification.

React SDK

React Native SDK

Server SDK

API Reference

verifyAuth() — SocketFi Backend Token Verification

Function signature

Parameters

Return value

On success

On failure

Extracting the token from the Authorization header

Success example

Failure example

Complete protected route example

Error codes

​Function signature

​Parameters

​Return value

​On success

​On failure

​Extracting the token from the Authorization header

​Success example

​Failure example

​Complete protected route example

​Error codes

Function signature

Parameters

Return value

On success

On failure

Extracting the token from the Authorization header

Success example

Failure example

Complete protected route example

Error codes