Core Principles
SocketFi authentication is designed around five principles that shape every decision in the system.Passwordless
Users never create, manage, or reset passwords. Authentication happens entirely through passkeys backed by biometrics or device PINs.
Secure By Default
Every authentication request uses modern WebAuthn standards — phishing-resistant, device-backed, and protected by hardware-grade cryptography.
Wallet-Aware
Authentication and wallet ownership are inseparable. A successful login immediately resolves the user’s smart wallet — no separate wallet-connect step required.
Recoverable
If a user loses access to their credential, recovery mechanisms let them replace it without changing wallet ownership or moving assets.
User-Centric
Authentication uses interfaces users already understand — Face ID, Touch ID, Windows Hello, and Android Passkeys — rather than blockchain-specific concepts.
How Authentication Works
When a user authenticates, SocketFi moves through four sequential stages. Each stage has a single responsibility.Authentication Events
Your application will encounter four distinct authentication events during a user’s lifecycle.1
Registration
A new user creates a passkey. SocketFi simultaneously deploys a smart wallet and binds the passkey credential to it. Both the user identity and the wallet are created in a single atomic flow.
2
Sign In
A returning user verifies their existing passkey. SocketFi locates their existing wallet and issues a fresh session token. No new wallet is created.
3
Session Expiration
Sessions are time-limited. When a token expires, you prompt the user to re-authenticate. The wallet is unchanged — only the session token is refreshed.
4
Recovery
A user who has lost access to their device or credential initiates recovery. A new passkey is registered and bound to the existing wallet. Wallet ownership and assets remain untouched.
Authentication Outcomes
Every authentication attempt produces one of three outcomes.Session object containing the user profile and a signed socketfiAccessToken.
Authentication Failure — Verification fails (cancelled by user, invalid credential, or hardware error). No session is created and no wallet access is granted.
Recovery Required — The credential cannot be found on the current device. The user is directed to a recovery flow that issues a replacement credential while preserving wallet ownership.
The Full Lifecycle
A complete authentication lifecycle — from first visit through session expiration — looks like this:Authentication vs. Authorization
Authentication and authorization are distinct concepts in SocketFi.
Authentication always occurs first. Your backend verifies the session token to establish authorization for every protected operation.
Session Tokens
Every successful authentication produces a SocketFi access token — a signed JWT your application uses to identify the authenticated user in API requests.Bearer header on requests to your backend, then verify it server-side using the SocketFi Server SDK. Never grant access to protected resources based solely on a client-provided identity claim.
Security Highlights
SocketFi authentication includes several layers of protection that work without any configuration on your part.- Challenge-based verification — Every authentication uses a fresh one-time challenge, preventing replay attacks.
- Device-backed credentials — Private keys live inside the Secure Enclave, TPM, or TEE and never leave the hardware.
- Phishing resistance — Passkeys are origin-bound; they cannot be used on a different domain.
- Short-lived sessions — Tokens expire automatically, limiting the window of exposure if a token is intercepted.
- Server-side verification — The
@socketfi/serverSDK cryptographically validates every token, independent of client state.