Skip to main content
Sign In With Ethereum (SIWE) lets users authenticate by signing a structured message with their Ethereum wallet. No password. No email. The server verifies the signature came from the claimed address, then creates a session. The standard is EIP-4361. It works with any wallet that supports personal_sign: MetaMask, WalletConnect, Coinbase Wallet, Rainbow, and others.

Setup

1

Add the plugin

lib/theauth.ts
2

Add a signature verifier (production)

Out of the box, the plugin validates message structure, domain, URI, version, and nonce but does not do secp256k1 signature recovery. For production, pass a verifySignature function using viem or ethers:
lib/theauth.ts
Without verifySignature, the plugin trusts the address in the message body and only checks that a signature string of at least 10 characters is present. Anyone can forge a sign-in by submitting a valid-looking message with a made-up signature. Always add signature recovery before going to production.

Sign-in flow

SIWE requires three steps: get a nonce, sign a message in the wallet, then submit both to the server.
1

Get a nonce

GET /auth/siwe/nonceRequest a server-generated nonce before building the sign-in message. Nonces are single-use and expire after 5 minutes (configurable). They are held in memory in the server process, so run the nonce and verify requests against the same instance.
2

Build and sign the message

Construct the EIP-4361 message string from the user’s address, the nonce, and your app metadata. Pass it to the wallet for signing.
The message the user sees in their wallet looks like:
3

Verify and start a session

POST /auth/siwe/verifySubmit the original message and the wallet signature. On success, the server returns the verified Ethereum address and chain ID. The endpoint does not create a user or a session, so create those in your own code from here.
Response, 200 OK

Nonce lifecycle

Every sign-in attempt must use a fresh nonce from the server. Nonces:
  • Are 16 random bytes, hex encoded (32 characters, 128 bits of entropy)
  • Expire after nonceTtlSeconds (default: 300 seconds)
  • Are deleted as soon as the message passes the format, domain, URI, version and nonce checks, before the signature is checked, so a failed signature check also consumes the nonce
The nonce is embedded in the signed message, so it cannot be stripped or replaced after signing. This prevents replay attacks: a captured (message, signature) pair from one session cannot be submitted again. If the nonce expires before the user signs, the verify endpoint returns 400 with "Nonce expired". An unknown or already used nonce returns 400 with "Nonce not found or already used". Request a new nonce and rebuild the message.

Linking wallets to users

SIWE verifies an address, it does not create or look up a user by itself. After a successful /auth/siwe/verify, use the returned address to find an existing user record or create a new one in your own storage, then create a session with the session manager (available when auth.session is configured):
theauth.auth.session.create(userId) returns { session, token }. Send token to the client as a cookie or bearer token.

Endpoints

Configuration reference

Security considerations

Always add verifySignature in production. Without it, the plugin validates message structure and nonce state, but anyone can submit a well-formed SIWE message for any address without a real signature. Domain and URI binding. The plugin rejects messages where domain or uri do not match the server’s config exactly. This prevents phishing attacks where a malicious site captures a signature meant for a different origin. Nonce reuse prevention. Nonces are deleted once the message passes the structural, domain, URI, version and nonce checks, including when the signature check then fails. A second attempt with the same nonce always fails. Chain ID. The chain ID in the message is returned to your application but is not enforced by the plugin. If your app is chain-specific (e.g. only Ethereum mainnet), check that chainId === 1 (or your expected value) after verification.

Passkey

Device biometric auth as another password-free option.

Magic link

Email-based passwordless sign-in with single-use links.

Anonymous auth

Guest sessions you can upgrade into a real account later.

Authentication overview

All sign-in methods available in theAuth.
Last modified on October 7, 2026