Credential Rotation: Update Your Passkey Proactively

Credential rotation lets you replace the passkey bound to your wallet while you still have access to the current one. It is a proactive operation — you choose to rotate because you got a new phone, you are retiring an old device, or you want to practice good security hygiene. Rotation is distinct from account recovery: rotation requires your current credential to authorize the change, while recovery is for situations where that credential is already lost.

Rotation vs Recovery

The two operations look superficially similar but serve different purposes and follow different authorization paths:

	Credential Rotation	Account Recovery
When to use	You still have your current passkey	You have lost your current passkey
Authorization required	Current passkey signs the rotation	Identity verification (no passkey needed)
User initiates from	Account settings	Recovery / login flow
Proactive or reactive?	Proactive	Reactive
Wallet address changes?	No	No
Assets move?	No	No
Ownership changes?	No	No

If you have already lost access to your passkey, use account recovery instead. Credential rotation cannot proceed without the current credential.

What Rotation Guarantees

The wallet contract’s rotate_passkey() operation provides a hard guarantee: only the bound credential changes. The entire rest of the wallet state is untouched. Before rotation:

Wallet address:  CDXXXXXXXXXX...
Assets:          500 USDC, 100 XLM
Policies:        500 USDC/day spending limit
Bound credential: Passkey A (old phone)

After rotation:

Wallet address:  CDXXXXXXXXXX...   ← unchanged
Assets:          500 USDC, 100 XLM ← unchanged
Policies:        500 USDC/day limit ← unchanged
Bound credential: Passkey B (new phone) ← updated

The Rotation Flow

Authenticate

The user authenticates with their current passkey. This proves they still control the wallet and authorizes the rotation request.

const session = await socketfi.authenticate();
// session confirms: user controls the currently bound passkey

Generate New Credential

The user creates a new passkey on the target device — the one they want to use going forward. The new passkey produces a public key and credential ID that will replace the current binding.

New device / new passkey provider
  ↓
WebAuthn credential created
  ↓
New public key + credential ID ready

Proof of Possession

The new passkey must prove it actually controls the private key it claims to have. SocketFi issues a challenge, the new passkey signs it, and the signature is verified before the rotation can proceed. This step prevents an attacker from injecting a credential they do not control.

Challenge issued for new credential
  ↓
New passkey signs challenge
  ↓
Proof of possession verified ✅

Rotation Authorized

The current passkey signs an authorization message that includes the new credential’s public key, the wallet’s current nonce, and an expiration window. This binds the current owner’s approval to the specific new credential being registered.

Authorization message:
─────────────────────
Wallet:         CDXXXXXXXXXX...
Action:         rotate_passkey
New credential: [new public key]
Nonce:          42
Expiration:     ledger 12,600
─────────────────────
Signed by: Passkey A (current)

Wallet Updated

The wallet contract verifies the authorization (current credential signature, nonce, expiration) and the proof of possession (new credential’s challenge response). Both must pass. If they do, the passkey rotation executes and the new credential becomes the active binding.

const result = await socketfi.requestTransaction({
  contractId: walletAddress,
  method: "rotate_passkey",
  args: {
    newCredential: newPasskeyCredential,
    proofOfPossession: challengeResponse,
  },
});

// result.success === true
// Passkey B is now the wallet's bound credential
// Passkey A no longer authorizes wallet operations

When to Rotate

Getting a new device

Rotate before you wipe or dispose of your old device. Authenticate on the old device, register the new passkey, rotate — then the old device’s passkey no longer controls the wallet.

Security policy compliance

Organizations that require periodic credential refresh can implement a rotation schedule without migrating assets or changing wallet addresses.

Migrating passkey providers

Moving from a hardware security key to a platform passkey (or vice versa) is a rotation — same wallet, new credential.

Proactive security

If you suspect your passkey may have been compromised but you still have access, rotate immediately rather than waiting for unauthorized activity.

Rotation Failure Scenarios

Rotation can fail at three points:

Failure	Cause	Resolution
Authorization rejected	Current passkey signature is invalid or the nonce does not match	Re-authenticate and retry with a fresh authorization
Proof of possession failed	The new credential could not sign the challenge correctly	Ensure the new passkey was correctly created; retry credential generation
Expired request	The authorization window expired before submission	Retry — the SDK will generate a fresh expiration window

If rotation fails after you have already set up the new passkey but before it was bound to the wallet, your current passkey is still active. You can retry rotation as many times as needed while your current credential remains valid.

Application Integration

Surface credential rotation in your application’s account or security settings so users can proactively manage their credentials before they lose access:

// Initiate a credential rotation flow
async function initiateCredentialRotation(walletAddress: string) {
  // Step 1: authenticate (proves current credential is valid)
  const session = await socketfi.authenticate();

  // Step 2: request the passkey rotation transaction.
  // The SDK handles new passkey creation and proof-of-possession internally,
  // then prompts the current passkey to sign the rotation authorization.
  const result = await socketfi.requestTransaction({
    contractId: walletAddress,
    method: "rotate_passkey",
    args: {},
  });

  if (result.success) {
    // Rotation complete — notify the user.
    // Their next login will use the new passkey.
  }

  return result;
}

Notify users by email or push notification when a credential rotation completes. Unexpected rotation notifications are an important signal that their account may be compromised.

Get Started

Authentication

Embedded Wallets

Transactions

Smart Wallet

Security

Credential Rotation: Update Your Passkey Proactively

Rotation vs Recovery

What Rotation Guarantees

The Rotation Flow

When to Rotate

Getting a new device

Security policy compliance

Migrating passkey providers

Proactive security

Rotation Failure Scenarios

Application Integration

​Rotation vs Recovery

​What Rotation Guarantees

​The Rotation Flow

​When to Rotate

Getting a new device

Security policy compliance

Migrating passkey providers

Proactive security

​Rotation Failure Scenarios

​Application Integration

Rotation vs Recovery

What Rotation Guarantees

The Rotation Flow

When to Rotate

Rotation Failure Scenarios

Application Integration