Setup
Sign-in flow
SIWE requires three steps: get a nonce, sign a message in the wallet, then submit both to the server.1
2
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
(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 addverifySignature 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.
Related
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.