#Keys and Storage

This guide shows you how to create a Wallet SDK instance, initialize a signing identity, and configure key-use authorization. The SDK stores credentials in an encrypted on-device database and keeps signing keys in the platform keystore.

Signing identity: A P-256 holder key bound to a did:jwk, plus the policy that protects that key.

#Prerequisites

Before you begin, ensure you have:

• The Wallet SDK on your platform — Follow Integrate the SDK for library setup.
• A resumed Android FragmentActivity — Required for each protected signing prompt on Android.
• NSFaceIDUsageDescription on iOS — Required for biometric signing.

#Create a Wallet

walletId / walletID is an application-level identity. Treat it as stable: it names the encrypted database and related key material.

val config = MobileWalletConfig(walletId = "consumer-wallet")
val wallet = MobileWalletFactory(context).create(config)

Default persistence is encrypted SQLDelight with SQLCipher. The SDK generates a database key, stores it in platform-protected storage, and does not fall back to plaintext. Signing keys always remain platform-managed. You can override credential or DID stores independently if your app owns that durability.

#Signing Identity

Call signingIdentity.initialize() before issuance or presentation that needs holder keys. New identities use P-256 and did:jwk.

when (val result = wallet.signingIdentity.initialize()) {
    is SigningIdentityOperationResult.Active -> openWallet(result.identity)
    is SigningIdentityOperationResult.Pending -> showPendingSetup(result.identityId)
    is SigningIdentityOperationResult.Failed -> showFailure(result.reason)
}

🎉 You've created a wallet with an active signing identity.

List stored credentials with wallet.credentials() and remove one with wallet.deleteCredential(id).

#Key-Use Authorization

New keys default to biometric current set: strong biometrics, no device-credential fallback, P-256. Restored keys keep the policy they were created with. Changing the wallet default never weakens an existing key.

• Biometric current set — Invalidates the key when the biometric enrollment set changes. Requires a physical Secure Enclave device for hardware signing on iOS.
• Biometric timed reuse — A 1–30 second reuse window after successful strong-biometric authorization. This is recent platform authentication, not consent for a wallet action.
• None — Unprotected signing. Select it explicitly when you need it.

Call keyUseAuthorizationPreflight to check whether a policy is supported before creating a key.

Optional attestationConfig / WalletConfiguration.attestation supplies OAuth client attestation when an issuer requires it.

#Next Steps

• Back up the signing identity — Backup and Recovery.
• Separate app unlock from signing policy — Security.
• Run your first holder flow — Integrate the SDK.