> ## 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 Sign-Up Flow: Passkey Registration & Wallet

> How SocketFi registers new users: passkey creation, credential verification, smart wallet deployment, and returning an authenticated session.

When a new user arrives at your application and authenticates for the first time, SocketFi does far more than create an account record. It simultaneously creates a passkey credential, deploys a smart wallet on-chain, binds the credential to that wallet, and returns a ready-to-use session — all from a single SDK call. The user never sees a seed phrase, a wallet address, or a blockchain configuration screen. From their perspective, they simply tapped Face ID and got in.

## The Registration Flow

The complete sign-up process moves through five stages from the moment the user taps your sign-up button to the moment your application receives a session.

<Steps>
  <Step title="User Initiates Sign-Up">
    The user clicks your sign-up or "Get Started" button. Your application calls `socketfi.authenticate()`. SocketFi detects that no existing account is associated with the current device and begins the registration flow rather than the sign-in flow.

    ```typescript theme={null}
    const session = await socketfi.authenticate();
    ```

    That's the only line of code your application needs. Everything else happens inside the SDK and SocketFi's backend.
  </Step>

  <Step title="Passkey Created">
    SocketFi generates a cryptographic registration challenge and passes it to the browser's WebAuthn API. The user's authenticator (Face ID, Touch ID, Windows Hello, etc.) prompts the user for biometric or PIN confirmation, then generates a new public-private key pair.

    The private key is stored inside secure hardware and **never transmitted**. The public key and a signed registration response are returned to SocketFi for verification.

    ```text theme={null}
    SocketFi Challenge
      ↓
    Platform Authenticator (Face ID / Touch ID / Windows Hello / etc.)
      ↓
    User Confirms (biometric or PIN)
      ↓
    Key Pair Generated
      ├── Private Key → Secure Enclave / TPM / TEE (never leaves device)
      └── Public Key  → Returned to SocketFi
    ```
  </Step>

  <Step title="Credential Verified">
    SocketFi validates the registration response:

    * The challenge matches the one issued for this request
    * The attestation signature is cryptographically valid
    * The credential ID is unique and not already registered
    * The registration metadata passes integrity checks

    Only credentials that pass all verification checks may proceed to wallet deployment. Any tampered or replayed registration response is rejected.
  </Step>

  <Step title="Wallet Deployed">
    With a verified credential in hand, SocketFi automatically deploys a smart wallet for the new user. This step is completely invisible to the user — no gas fee prompt, no wallet address to copy, no network selection.

    ```text theme={null}
    Verified Credential
      ↓
    Deploy Smart Wallet
      ↓
    Generate Wallet Address
      ↓
    Bind Passkey Credential to Wallet
      ↓
    Wallet Active
    ```

    The newly deployed wallet can immediately receive assets, interact with contracts, and authorize transactions. The passkey credential is stored as the wallet's primary authorized signer.
  </Step>

  <Step title="Session Created">
    SocketFi issues a signed session and returns it to your application. The user is now authenticated and their wallet is immediately accessible.

    ```typescript theme={null}
    // session is the return value of socketfi.authenticate()
    {
      userProfile: {
        id: "usr_01HXYZ",
        username: "alice"
      },
      socketfiAccessToken: "eyJhbGciOiJFUzI1NiJ9..."
    }
    ```
  </Step>
</Steps>

***

## The Authentication Response

After a successful sign-up, `socketfi.authenticate()` resolves with a `Session` object:

```typescript theme={null}
const session = await socketfi.authenticate();

console.log(session.userProfile.id);          // "usr_01HXYZ"
console.log(session.socketfiAccessToken);     // "eyJhbGciOi..."
```

```typescript theme={null}
// Full Session type
interface Session {
  userProfile: {
    id: string;         // Stable user identifier — use this as your foreign key
    username?: string;  // Display name, if set during registration
  };
  socketfiAccessToken: string; // Signed JWT — include in Authorization: Bearer headers
}
```

Store the `socketfiAccessToken` and attach it to every request you make to your backend. Verify it server-side before granting access to any protected resource.

***

## What the User Experiences

From the user's perspective, the entire flow takes a few seconds:

```text theme={null}
Tap "Get Started"
  ↓
Face ID / Touch ID / Windows Hello prompt
  ↓
Biometric confirmation
  ↓
Inside the application
```

They never encounter:

* A password field or confirmation box
* A seed phrase or recovery key to copy down
* A wallet address to save
* A network or chain selection screen
* A gas fee or transaction confirmation

The embedded wallet exists from this moment forward. Users can access it again later by simply re-authenticating — no import, no migration, no setup.

***

## Wallet Ownership

The wallet created during sign-up belongs entirely to the user. SocketFi deploys and indexes it, but does not hold custody:

* SocketFi does **not** own the wallet
* SocketFi does **not** hold the user's private keys
* SocketFi does **not** control the assets inside the wallet

The passkey credential — stored on the user's device — is the proof of ownership. Wallet access is only possible by producing a valid signature from that credential.

***

## Error Handling

Not every sign-up attempt completes successfully. Handle these scenarios gracefully in your application:

<CodeGroup>
  ```typescript User Cancelled theme={null}
  try {
    const session = await socketfi.authenticate();
  } catch (err) {
    if (err.code === "USER_CANCELLED") {
      // User dismissed the biometric prompt — allow retry
      showRetryButton();
    }
  }
  ```

  ```typescript Authentication Failed theme={null}
  try {
    const session = await socketfi.authenticate();
  } catch (err) {
    if (err.code === "AUTHENTICATION_FAILED") {
      // The registration response failed server-side validation
      showErrorMessage("Registration failed. Please try again.");
    }
  }
  ```
</CodeGroup>

<Note>
  Wallet deployment is idempotent. If a deployment fails partway through, retrying `socketfi.authenticate()` will not create a duplicate wallet.
</Note>