> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socket.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# SocketFi Authentication Overview: Passkeys & Sessions

> Learn how SocketFi's passkey-based, wallet-aware authentication model works — from identity verification through wallet resolution to session creation.

SocketFi authentication is the gateway to the entire platform. Every interaction with an embedded smart wallet begins here: a user proves who they are with a passkey, SocketFi resolves their wallet, and your application receives a signed session token it can use immediately. There are no passwords, no seed phrases, and no external wallet software for users to install or manage.

## Core Principles

SocketFi authentication is designed around five principles that shape every decision in the system.

<CardGroup cols={2}>
  <Card title="Passwordless" icon="lock-open">
    Users never create, manage, or reset passwords. Authentication happens entirely through passkeys backed by biometrics or device PINs.
  </Card>

  <Card title="Secure By Default" icon="shield-check">
    Every authentication request uses modern WebAuthn standards — phishing-resistant, device-backed, and protected by hardware-grade cryptography.
  </Card>

  <Card title="Wallet-Aware" icon="wallet">
    Authentication and wallet ownership are inseparable. A successful login immediately resolves the user's smart wallet — no separate wallet-connect step required.
  </Card>

  <Card title="Recoverable" icon="rotate">
    If a user loses access to their credential, recovery mechanisms let them replace it without changing wallet ownership or moving assets.
  </Card>
</CardGroup>

<Card title="User-Centric" icon="user">
  Authentication uses interfaces users already understand — Face ID, Touch ID, Windows Hello, and Android Passkeys — rather than blockchain-specific concepts.
</Card>

***

## How Authentication Works

When a user authenticates, SocketFi moves through four sequential stages. Each stage has a single responsibility.

```text theme={null}
User
  ↓
Passkey Challenge
  ↓
Identity Verified
  ↓
Wallet Resolved
  ↓
Session Created
  ↓
Application Access
```

| Stage                 | What Happens                                                         |
| --------------------- | -------------------------------------------------------------------- |
| **Passkey Challenge** | A unique cryptographic challenge is sent to the user's authenticator |
| **Identity Verified** | The signed response proves control of the registered credential      |
| **Wallet Resolved**   | The verified identity is mapped to the user's smart wallet address   |
| **Session Created**   | A signed JWT access token is issued for your application to use      |

***

## Authentication Events

Your application will encounter four distinct authentication events during a user's lifecycle.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## Authentication Outcomes

Every authentication attempt produces one of three outcomes.

```text theme={null}
┌─────────────────────────────────────────────────────────┐
│                  authenticate()                         │
├──────────────┬──────────────────┬───────────────────────┤
│   Verified   │  Verification    │  Credential Missing   │
│              │  Failed          │                       │
│      ↓       │       ↓          │          ↓            │
│  Session     │  Access          │  Recovery             │
│  Created     │  Denied          │  Flow                 │
└──────────────┴──────────────────┴───────────────────────┘
```

**Successful Authentication** — The user's passkey is verified, their wallet is resolved, and your app receives a `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:

```text theme={null}
New User                        Returning User
   ↓                                  ↓
Create Passkey              Verify Existing Passkey
   ↓                                  ↓
Deploy Wallet               Resolve Existing Wallet
   ↓                                  ↓
Create Session              Create Session
   ↓                                  ↓
Application Access          Application Access
   ↓                                  ↓
Session Expires             Session Expires
   ↓                                  ↓
Re-authenticate             Re-authenticate
   ↓                                  ↓
New Session (same wallet)   New Session (same wallet)
```

The wallet is permanent. Sessions are temporary. Ownership never changes because of authentication activity.

***

## Authentication vs. Authorization

Authentication and authorization are distinct concepts in SocketFi.

| Concept            | Question Answered | Example                                       |
| ------------------ | ----------------- | --------------------------------------------- |
| **Authentication** | Who are you?      | Passkey verified → user identity confirmed    |
| **Authorization**  | What can you do?  | Session token → permission to transfer assets |

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.

```typescript theme={null}
const session = await socketfi.authenticate();
// session.socketfiAccessToken  ← signed JWT
// session.userProfile.id       ← stable user identifier
```

Send this token as a `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.

<Tip>
  Read [Passkeys](/authentication/passkeys) to understand the cryptographic foundation of SocketFi authentication, or jump directly to [Backend Verification](/authentication/backend-verification) to see how to validate session tokens in your server.
</Tip>

***

## 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/server` SDK cryptographically validates every token, independent of client state.