What your application must persist for agent wallets, and the security model: key custody, signature encoding, and refresh limits.
The SDK is stateless: it persists nothing between calls. You own storage for every artifact in the agent wallet flow. This page lists what to store, where, and what happens if you lose it — and the security guarantees and obligations of the flow.
What you must persist
For storage mechanics (KMS envelope encryption, schemas, checklists), see Storage Best Practices.
Artifact
Storage class
Lifetime
If you lose it
Session private key (privateKeyJwk or KMS/HSM key)
Secrets vault, KMS, or HSM — or keep the key non-extractable in KMS and never materialize a JWK. Never a plain file or database column.
Life of the agent session
Signed-session proofs can no longer be produced; backup and recovery calls fail. Generate a new key pair and sign the user in again to bind it.
User JWT
Encrypted at rest in your app store, or memory only
Until refreshed or expired, bounded by refreshExp
The user signs in again. Update the stored value on everyrefreshAuthToken() call — the old token is superseded.
Backup password
Secrets vault. It is the PBKDF2 password for the key-share backup — never log it.
Life of the wallet
Dynamic-stored backups encrypted with it are permanently undecryptable.
Durable app store (Redis, Postgres). Non-sensitive.
Life of the wallet
fetchWalletMetadata recovers identity fields only — it does not return externalServerKeySharesBackupInfo, and no SDK endpoint does. Operations that need backup state (sign with auto-recovery, refresh, reshare, password checks) fail.
externalServerKeyShares
Secrets vault or HSM. Sensitive.
Life of the wallet
Recoverable from Dynamic only if backed up with backUpToDynamic: true; otherwise signing is permanently impossible.
Agent signing token (autonomous mode only)
Secrets vault, KMS, or HSM
Life of the agent’s Dynamic user identity
The Dynamic user is keyed to this key’s public address. Once the current JWT can no longer be refreshed, the agent cannot sign in as that user again, and the user’s wallets are unreachable through this flow.
Mutating operations (refreshWalletAccountShares, reshare, updatePassword) return new backupInfo. Merge it into your stored walletMetadata.externalServerKeySharesBackupInfo immediately — subsequent operations read stale metadata and fail otherwise.
Security
The session private key never enters the SDK. You supply signatures through getSessionSignature; custody stays with you (file-backed JWK, KMS, HSM, or enclave).
A leaked JWT alone does not authorize backup or recovery operations for a session-bound wallet. The keyshares relay requires the signed-session proof, which requires the session private key.
getSessionSignature must return lowercase hex (raw ECDSA P-256 r‖s, 64 bytes). Base64 corrupts the proof.
Do not log JWTs, OTP codes, backup passwords, or key material. The auth client surfaces error codes and messages only; your application must do the same.
Refresh is bounded. The JWT refreshExp claim is a hard server-side limit; when it is reached, refresh fails with a 401 and only a new sign-in restores access. Design your agent to detect this and re-run the sign-in flow — for a human user this requires their re-approval; with an agent signing token or a fresh JWT from your external issuer it is programmatic.
In autonomous mode, the agent signing token is the user identity. Anyone holding that key can sign in as that user and, with a new session key, operate its wallets. Custody it like the session private key: vault, KMS, or HSM — never source code or logs.