Authenticate with SIWE and JWT¶

This guide shows how to sign in to a StorageHub Main Storage Provider (MSP) using Sign-In with Ethereum (SIWE, EIP-4361) and maintain a session with short-lived JSON Web Tokens (JWTs). The MSP verifies a wallet-signed challenge, issues a JWT for subsequent requests, and resolves an ENS profile where available. The StorageHub SDK wraps this flow so you can check auth status, complete login, and fetch the authenticated profile with a few calls.

Prerequisites¶

Node.js v22+ installed

A TypeScript project

Need a starter project?

If you don't have an existing project, follow these steps to create a TypeScript project you can use to follow the guides in this section:

Create a new project folder by executing the following command in the terminal:
```
mkdir datahaven-project && cd datahaven-project
```
Initialize a package.json file using the correct command for your package manager:
pnpmyarnnpm
pnpm init
yarn init
npm init --y

Add the TypeScript and Node type definitions to your projects using the correct command for your package manager:

pnpmyarnnpm

pnpm add -D typescript ts-node @types/node

yarn add -D typescript ts-node @types/node

npm install -D typescript ts-node @types/node

Create a tsconfig.json file in the root of your project and paste the following configuration:

tsconfig.json

{
    "compilerOptions": {
        "target": "ES2022",
        "module": "nodenext",
        "moduleResolution": "NodeNext",
        "esModuleInterop": true,
        "strict": true,
        "skipLibCheck": true,
        "outDir": "dist",
        "declaration": true,
        "sourceMap": true
    },
    "include": ["src/**/*.ts"]
}

Initialize the src directory:
```
mkdir src && touch src/index.ts
```

Dependencies installed
Clients initialized

Set Up Auth Script¶

Create an index.ts file if you haven't already. Its run method will orchestrate all the logic in this guide. By now, your services folder (including the MSP and client helper services) should already be created, which means you should already have the authenticateUser helper method implemented. If not, see the Get Started guide.

Add the following code to your index.ts file:

index.ts

import '@storagehub/api-augment';
import { initWasm } from '@storagehub-sdk/core';
import { polkadotApi } from './services/clientService.js';
import { authenticateUser } from './services/mspService.js';

async function run() {
  // Initialize WASM
  await initWasm();

  // Authenticate address (e.g. before performing actions that require authentication
  // like uploading a file or retrieving private data)
  const authProfile = await authenticateUser();
  console.log('Authenticated user profile:', authProfile);

  await polkadotApi.disconnect();
}

run();

In this code, the authenticateUser helper method from mspService.ts is called. This method:

Checks and authenticates your address via the MSP Client.
Calls the SDK's mspClient.auth.SIWE method, which produces a JWT token used as proof of authentication.
Passes the JWT token to the sessionProvider constant, one of the two required parameters for MspClient.connect.

Take a look at the authenticateUser helper method code.

mspService.ts

// Authenticate the user via SIWE (Sign-In With Ethereum) using the connected wallet
// Once authenticated, store the returned session token and retrieve the user’s profile
const authenticateUser = async (): Promise<UserInfo> => {
  console.log('Authenticating user with MSP via SIWE...');

  // In development domain and uri can be arbitrary placeholders,
  // but in production they must match your actual frontend origin.
  const domain = 'localhost';
  const uri = 'http://localhost';

  const siweSession = await mspClient.auth.SIWE(walletClient, domain, uri);
  console.log('SIWE Session:', siweSession);
  sessionToken = (siweSession as { token: string }).token;

  const profile: UserInfo = await mspClient.auth.getProfile();
  return profile;
};

When you connect to the MSP with a valid sessionProvider, you can trigger certain methods you wouldn’t otherwise be able to:

MspClient.auth.getProfile: Returns the authenticated user's profile.
MspClient.files.uploadFile: Uploads a file to the MSP.
MspClient.info.getPaymentStreams: Returns the authenticated user's payment streams.

Run Auth Script¶

Execute the authenticateUser method by running the script:

ts-node index.ts

After the address has been authenticated, the authenticateUser method that triggers MspClient.auth.getProfile upon successful execution, should return a response like this:

Note

The ENS name is hardcoded currently.

ts-node index.ts

Authenticated user profile: {
  address: '0x00DA35D84a73db75462D2B2c1ed8974aAA57223e',
  ens: 'user.eth'
}

Next Steps¶

Last update: December 18, 2025
| Created: October 17, 2025