Siwe Fundamentals

Try it Live

Run SIWE examples in the interactive playground

Conceptual Guide - For API reference and method documentation, see SIWE API.

Sign-In with Ethereum (SIWE) is a decentralized authentication protocol that lets users prove address ownership by signing structured messages with their private keys. No OAuth, no passwords, no third parties - just cryptographic proof.

What is SIWE?

SIWE (EIP-4361) standardizes Ethereum-based authentication. Instead of usernames and passwords, users sign a message with their wallet to prove they control an address.

Why SIWE Exists

Traditional web authentication relies on centralized identity providers (Google, Twitter, etc.). SIWE enables:

Self-sovereign identity - Users own their credentials (private keys)
No intermediaries - Direct cryptographic proof, no OAuth handshakes
Privacy - No personal data required, just address ownership
Standardization - Common format for Ethereum authentication across dApps

Message Format

SIWE messages are human-readable structured text. Users read and sign them with wallets:

example.com wants you to sign in with your Ethereum account:
0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e

Sign in to Example App

URI: https://example.com/login
Version: 1
Chain ID: 1
Nonce: testnonce123
Issued At: 2024-11-06T12:00:00.000Z
Expiration Time: 2024-11-06T13:00:00.000Z

Message Components

Each field serves a specific security or usability purpose:

Domain - Origin where signing occurs (prevents phishing)
Address - Account performing authentication
Statement - Human-readable context (optional)
URI - Resource being accessed
Version - Protocol version (always “1”)
Chain ID - Which blockchain (prevents replay across chains)
Nonce - One-time random value (prevents replay attacks)
Issued At - Timestamp when message created
Expiration Time - When message becomes invalid (optional)
Not Before - When message becomes valid (optional)
Request ID - System identifier (optional)
Resources - List of granted URIs (optional)

Authentication Flow

SIWE follows a multi-step process:

Backend generates nonce, stores for 5 minutes
Frontend requests nonce
Frontend constructs SIWE message with nonce
User signs message with wallet (off-chain)
Frontend sends message + signature to backend
Backend verifies signature matches address
Backend checks nonce is valid and unused
Backend marks nonce as used, creates session
User authenticated

Why Nonces Matter

Without nonces, attackers could replay old signed messages to impersonate users. Nonces ensure each signature is single-use:

// Backend: Generate and store nonce
const nonce = Siwe.generateNonce(); // Random alphanumeric string
storeNonce(userId, nonce, expiresIn5Minutes);

// Frontend: Include nonce in message
const message = Siwe.create({
  domain: window.location.host,
  address: userAddress,
  uri: window.location.origin,
  chainId: 1,
  nonce, // From backend
});

// Backend: Verify nonce is valid and unused
if (!isValidNonce(message.nonce)) {
  throw new Error("Invalid or reused nonce");
}
markNonceUsed(message.nonce);

Complete Example: Authentication

Full authentication flow from message creation to verification:

Frontend
Backend

import { Siwe, Address } from 'tevm';

// 1. Request nonce from backend
const { nonce } = await fetch('/auth/nonce').then(r => r.json());

// 2. Create SIWE message
const message = Siwe.create({
  domain: window.location.host,
  address: Address(userAddress),
  uri: window.location.origin,
  chainId: await provider.getChainId(),
  statement: "Sign in to Example App",
  nonce,
});

// 3. Format for signing
const messageText = message.format();

// 4. User signs with wallet
const signature = await wallet.signMessage(messageText);

// 5. Send to backend for verification
const response = await fetch('/auth/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: messageText,
    signature
  }),
});

if (response.ok) {
  const { sessionToken } = await response.json();
  // Store session token, user is authenticated
}

import { Siwe, Address } from 'tevm';

// Generate nonce endpoint
app.get('/auth/nonce', (req, res) => {
  const nonce = Siwe.generateNonce();

  // Store nonce with 5 minute expiration
  storeNonce(req.sessionID, nonce, Date.now() + 5 * 60 * 1000);

  res.json({ nonce });
});

// Verify signature endpoint
app.post('/auth/verify', async (req, res) => {
  const { message: messageText, signature } = req.body;

  // Parse message
  const message = Siwe.parse(messageText);

  // Verify message structure and expiration
  const validation = Siwe.validate(message);
  if (!validation.valid) {
    return res.status(400).json({ error: validation.error });
  }

  // Verify nonce is valid and unused
  const storedNonce = getNonce(req.sessionID);
  if (!storedNonce || storedNonce !== message.nonce) {
    return res.status(401).json({ error: "Invalid or expired nonce" });
  }

  // Verify signature matches address
  if (!Siwe.verify(message, signature)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // Mark nonce as used (prevent replay)
  markNonceUsed(message.nonce);

  // Create authenticated session
  const sessionToken = createSession({
    address: Address.toHex(message.address),
    chainId: message.chainId,
  });

  res.json({ sessionToken });
});

Signing and Verification

SIWE uses EIP-191 personal sign standard:

import { Siwe, Address } from 'tevm';

const message = Siwe.create({
  domain: "example.com",
  address: Address("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e"),
  uri: "https://example.com",
  chainId: 1,
});

// Get message hash for signing (32 bytes)
const messageHash = message.getMessageHash();
// Prepends: "\x19Ethereum Signed Message:\n" + length + message

// User signs (wallet handles EIP-191 formatting)
const signature = await wallet.signMessage(message.format());

// Verify signature recovers to correct address
const isValid = message.verify(signature);
// Internally: ecrecover(hash, signature) === message.address

Combined Validation and Verification

Use verifyMessage() for complete validation:

const result = Siwe.verifyMessage(message, signature);

if (result.valid) {
  // Message structure valid, not expired, signature correct
} else {
  console.error(result.error.type); // "expired" | "signature_mismatch" | etc.
  console.error(result.error.message); // Human-readable explanation
}

Security Considerations

Domain Binding

Always verify the domain matches your origin to prevent phishing:

const message = Siwe.parse(messageText);

if (message.domain !== window.location.host) {
  throw new Error("Domain mismatch - possible phishing attack");
}

Attackers can’t use a signature from attacker.com on example.com because the domain is in the signed message.

Nonce Management

Implement proper nonce handling:

// Generate: cryptographically random
const nonce = Siwe.generateNonce(11); // Min 8 chars

// Store: with expiration (5-10 minutes typical)
storeNonce(nonce, expiresAt);

// Validate: check exists and not expired
if (!isValidNonce(nonce)) {
  throw new Error("Invalid or expired nonce");
}

// Consume: mark as used immediately after verification
markNonceUsed(nonce);

Expiration Times

Set reasonable expiration windows:

const message = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com",
  chainId: 1,
  expirationTime: new Date(Date.now() + 10 * 60 * 1000).toISOString(), // 10 minutes
});

// Later, validate expiration
const result = message.validate({ now: new Date() });
if (!result.valid && result.error.type === "expired") {
  // Request new signature
}

HTTPS in Production

Always use HTTPS in production to prevent man-in-the-middle attacks. SIWE doesn’t encrypt messages - they’re signed plaintext.

Common Use Cases

Authenticate users to access dApp features:

// User connects wallet
const address = await provider.getAddress();

// Create login message
const message = Siwe.create({
  domain: "dapp.example.com",
  address: Address(address),
  uri: "https://dapp.example.com",
  chainId: 1,
  statement: "Sign in to access your dashboard",
});

// Sign and verify
const signature = await signer.signMessage(message.format());
const result = Siwe.verifyMessage(message, signature);

if (result.valid) {
  // Grant access to dApp
}

Session Management

Create time-limited sessions:

const message = Siwe.create({
  domain: "example.com",
  address: userAddress,
  uri: "https://example.com",
  chainId: 1,
  expirationTime: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(), // 24 hours
});

// Store session
const session = {
  address: Address.toHex(message.address),
  expiresAt: message.expirationTime,
};

// Validate on each request
const validation = message.validate({ now: new Date() });
if (!validation.valid) {
  // Session expired, request re-authentication
}

Resource Authorization

Grant access to specific resources:

const message = Siwe.create({
  domain: "api.example.com",
  address: userAddress,
  uri: "https://api.example.com",
  chainId: 1,
  statement: "Access user profile and settings",
  resources: [
    "https://api.example.com/user/profile",
    "https://api.example.com/user/settings",
  ],
});

// Backend checks requested resource is in authorized list
function isAuthorized(message, requestedResource) {
  return message.resources?.includes(requestedResource) ?? false;
}

Resources

EIP-4361: Sign-In with Ethereum - Full specification
EIP-191: Signed Data Standard - Message signing format
siwe.xyz - Official SIWE website with tools and libraries
login.xyz - Reference implementation and examples

Next Steps

Overview - Type definition and API reference
Constructors - Create SIWE messages
Signing - Sign and hash messages
Verification - Verify signatures
Validation - Validate message structure
Usage Patterns - Real-world authentication flows

Overview

Getting Started

Core Concepts

Skills

JSONRPCProvider

Contract

Primitives

Cryptography

EVM

Utils

Guides

Examples

Swift

Zig

Developer Documentation

Generated API (TypeDoc)

Siwe Fundamentals

Try it Live

What is SIWE?

Why SIWE Exists

Message Format

Message Components

Authentication Flow

Why Nonces Matter

Complete Example: Authentication

Signing and Verification

Combined Validation and Verification

Security Considerations

Domain Binding

Nonce Management

Expiration Times

HTTPS in Production

Common Use Cases

Session Management

Resource Authorization

Resources

Next Steps

Overview

Getting Started

Core Concepts

Skills

JSONRPCProvider

Contract

Primitives

Cryptography

EVM

Utils

Guides

Examples

Swift

Zig

Developer Documentation

Generated API (TypeDoc)

Try it Live

​What is SIWE?

​Why SIWE Exists

​Message Format

​Message Components

​Authentication Flow

​Why Nonces Matter

​Complete Example: Authentication

​Signing and Verification

​Combined Validation and Verification

​Security Considerations

​Domain Binding

​Nonce Management

​Expiration Times

​HTTPS in Production

​Common Use Cases

​dApp Login

​Session Management

​Resource Authorization

​Resources

​Next Steps

What is SIWE?

Why SIWE Exists

Message Format

Message Components

Authentication Flow

Why Nonces Matter

Complete Example: Authentication

Signing and Verification

Combined Validation and Verification

Security Considerations

Domain Binding

Nonce Management

Expiration Times

HTTPS in Production

Common Use Cases

dApp Login

Session Management

Resource Authorization

Resources

Next Steps