> ## 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.
# Credential Rotation: Update Your Passkey Proactively
> Rotate the passkey bound to your wallet when you get a new device or upgrade security — wallet address, assets, and history stay completely unchanged.
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](/smart-wallet/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:**
```text theme={null}
Wallet address: CDXXXXXXXXXX...
Assets: 500 USDC, 100 XLM
Policies: 500 USDC/day spending limit
Bound credential: Passkey A (old phone)
```
**After rotation:**
```text theme={null}
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
The user authenticates with their current passkey. This proves they still control the wallet and authorizes the rotation request.
```typescript theme={null}
const session = await socketfi.authenticate();
// session confirms: user controls the currently bound passkey
```
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.
```text theme={null}
New device / new passkey provider
↓
WebAuthn credential created
↓
New public key + credential ID ready
```
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.
```text theme={null}
Challenge issued for new credential
↓
New passkey signs challenge
↓
Proof of possession verified ✅
```
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.
```text theme={null}
Authorization message:
─────────────────────
Wallet: CDXXXXXXXXXX...
Action: rotate_passkey
New credential: [new public key]
Nonce: 42
Expiration: ledger 12,600
─────────────────────
Signed by: Passkey A (current)
```
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.
```typescript theme={null}
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
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.
Organizations that require periodic credential refresh can implement a rotation schedule without migrating assets or changing wallet addresses.
Moving from a hardware security key to a platform passkey (or vice versa) is a rotation — same wallet, new credential.
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:
```typescript theme={null}
// 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.