Sign-In Flow — Returning User Authentication in SocketFi

When a returning user authenticates, SocketFi does not create anything new — no wallet deployment, no key generation. Instead, the SDK verifies that the user controls the same passkey credential registered during sign-up, then looks up their existing wallet and issues a fresh session token. The entire flow takes a few seconds and requires nothing from the user beyond a biometric confirmation.

User Initiates Authentication

The user clicks your sign-in button and your application calls socketfi.authenticate(). The SDK detects an existing account associated with the device and begins the sign-in flow rather than the registration flow.

const session = await socketfi.authenticate();

The call is identical for sign-up and sign-in. SocketFi handles the routing automatically based on whether a registered credential exists for the current device.

Passkey Challenge Issued

SocketFi generates a unique one-time challenge and passes it to the browser’s WebAuthn API. The platform prompts the user with their registered authenticator.

SocketFi Authentication Challenge (unique, expires quickly)
  ↓
Browser WebAuthn API
  ↓
Platform Authenticator Prompt (Face ID / Touch ID / Windows Hello / etc.)

No challenge is ever reused. If an attacker intercepts a signed response from a previous session, it cannot be replayed against a new challenge.

Signature Verified

The user confirms their identity through biometrics or PIN. The authenticator signs the challenge with the private key stored in secure hardware and returns the signature.SocketFi verifies three things:

The challenge matches the one issued for this request
The signature is valid against the registered public key
The credential ID belongs to an active, registered account

If any of these checks fail, authentication is denied and no session is created.

User Confirms (Face ID / fingerprint / PIN)
  ↓
Authenticator Signs Challenge with Private Key
  ↓
Signature Returned to SocketFi
  ↓
Verified Against Registered Public Key
  ↓
Identity Confirmed

Wallet Resolved

Once identity is confirmed, SocketFi maps the verified credential to the user’s wallet address. No new wallet is created or deployed.

Verified Credential ID
  ↓
User Profile Lookup
  ↓
Existing Wallet Address Retrieved
  ↓
Wallet Resolved

The wallet address, balances, transaction history, and all associated state remain exactly as the user left them.

Session Returned

SocketFi creates a new session and returns it to your application. The user is authenticated and their wallet is accessible.

{
  userProfile: {
    id: "usr_01HXYZ",
    username: "alice"
  },
  socketfiAccessToken: "eyJhbGciOiJFUzI1NiJ9..."
}

Note that socketfiAccessToken is a new signed token even though the wallet address is unchanged. Previous tokens from earlier sessions are not refreshed — you always need the latest token from a successful authenticate() call.

The Session Response

Sign-in returns the same Session structure as sign-up:

const session = await socketfi.authenticate();

// Attach the token to every backend request
const response = await fetch("/api/dashboard", {
  headers: {
    Authorization: `Bearer ${session.socketfiAccessToken}`,
  },
});

Your backend can extract the user ID and wallet address by verifying the token — see Backend Verification.

Multi-Device Authentication

Users who have set up passkeys on multiple devices can authenticate from any of them. Each device holds its own copy of the passkey private key — authentication on one device does not affect the ability to authenticate from another.

iPhone (Face ID)       MacBook (Touch ID)      YubiKey
      ↓                       ↓                    ↓
Passkey A              Passkey B              Passkey C
      ↓                       ↓                    ↓
            Same Wallet — Same Wallet Address

The number of simultaneously registered credentials per user depends on your SocketFi application configuration. Review your platform settings if you need to adjust credential limits.

Session Expiration and Re-Authentication

Sessions are time-limited. Once a socketfiAccessToken expires, your backend will reject requests that include it. Design your application to handle this gracefully:

async function fetchWithAuth(url: string) {
  let token = getStoredToken();

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (response.status === 401) {
    // Token has expired — prompt the user to re-authenticate
    const session = await socketfi.authenticate();
    token = session.socketfiAccessToken;
    storeToken(token);

    // Retry the original request with the new token
    return fetch(url, {
      headers: { Authorization: `Bearer ${token}` },
    });
  }

  return response;
}

Re-authentication creates a brand-new session token. The wallet address remains unchanged.

Failure Scenarios

Handle these cases to provide a smooth experience for your users.

try {
  const session = await socketfi.authenticate();
} catch (err) {
  if (err.code === "USER_CANCELLED") {
    // User dismissed the prompt — show a retry option, don't log an error
    showSignInButton();
  }
}

try {
  const session = await socketfi.authenticate();
} catch (err) {
  if (err.code === "AUTHENTICATION_FAILED") {
    // Credential verification failed — may indicate a device or credential issue
    showErrorMessage("Authentication failed. Try a different device or use account recovery.");
  }
}

// Caught on your backend, not the SDK
// HTTP 401 response from your API signals an expired token
if (response.status === 401) {
  const session = await socketfi.authenticate();
  retryWithNewToken(session.socketfiAccessToken);
}

Never treat a failed socketfi.authenticate() call as a successful sign-in. Always wait for the Promise to resolve successfully and check that the returned socketfiAccessToken is present before granting access to protected features.

Sign-in is explicitly non-destructive. Nothing about the user’s wallet or account changes:

Item	Changed During Sign-In?
Wallet address	No
Asset balances	No
Transaction history	No
Registered credentials	No
Wallet ownership	No
Session token	Yes — a fresh token is always issued

The session token is the only thing that changes. Everything else persists from the last time the user was active.

Get Started

Authentication

Embedded Wallets

Transactions

Smart Wallet

Security

Sign-In Flow — Returning User Authentication in SocketFi

The Session Response

Multi-Device Authentication

Session Expiration and Re-Authentication

Failure Scenarios

​The Sign-In Flow

​The Session Response

​Multi-Device Authentication

​Session Expiration and Re-Authentication

​Failure Scenarios

​What Doesn’t Change During Sign-In

The Sign-In Flow

The Session Response

Multi-Device Authentication

Session Expiration and Re-Authentication

Failure Scenarios

What Doesn’t Change During Sign-In