Authentication

HeartBadge uses passkey-first authentication today. But we're designed for authentication's future. This page explains what that means, how it works now, and why the architecture doesn't lock us into any single method.

Why passkey-first

Passkeys are the modern standard for a reason:

• Passwordless. No passwords to remember, rotate, or forget.
• Phishing-resistant. Credentials are cryptographic and bound to the domain. You can't accidentally give them to an imposter.
• Works everywhere. Passkeys live on your device (phone, laptop, security key) and sync across them. They work offline and online.
• Fast. One tap or biometric, and you're in. No codes to enter.

The authentication stack today

Primary: Passkey

Your badge identity is tied to a passkey stored on your device. When you sign in, you authenticate with the passkey (usually a biometric or device unlock). The server verifies the assertion and grants you access to your badge.

Secondary: Two-Factor Auth

For sensitive actions (high-value sends, security changes, key exports), we require a second factor: a TOTP code from your authenticator app. 2FA is optional but recommended for accounts with balances. See Two-Factor Auth.

Recovery: Email

If you lose access to your device, verified email is your recovery path. See Email Verification.

Why we stay agnostic

The platform doesn't care how you prove who you are. It cares that you can prove it cryptographically, consistently, and in a way that survives whatever security advances come next.

Today: passkeys. Tomorrow: maybe bioretinal scans, maybe something we haven't invented yet. The badge identity layer is abstract enough that we can swap the mechanism (how you prove) without changing the protocol (what it means to be you).

This is how we avoid the "king of auth" trap. We're not betting that passkeys are forever. We're betting that cryptographic proof is forever, and that the proof method is just infrastructure.

How identity is bound to the badge

Your badge has a seed phrase. From that seed, two keys are derived:

• Identity key. Proves who you are. Used to authenticate sessions and sign attestations.
• Spend key. Proves you control the badge's rewards. Used to sign reward transfers.

The passkey doesn't hold those keys. It proves you know the seed phrase that derives them. The actual keys live in your badge contract on the chain.

If the authentication method changes (passkey → bioretinal → something else), the identity and spend keys stay the same. You're still you. The proof method just evolved.

For developers integrating with HeartBadge

If you're building a program or service that uses HeartBadge identity:

• Don't assume the auth method. Build against the identity layer, not the mechanism. Your integration should work whether a member proved themselves with a passkey, a fingerprint, or a retinal scan.
• Request identity proofs, not credentials. Ask the member to prove their identity (by signing a challenge with their identity key), don't ask for auth method details.
• Validate signatures, not sessions. Trust what you can verify cryptographically, not what someone told you about how they logged in.

Future-proofing your integration

The protocol is designed so that authentication improvements don't break your integration:

• Session tokens are opaque. Don't parse or depend on them. Just hand them to the API.
• Challenge-response protocols stay the same. If you're building peer-to-peer trust (member A proving to member B that they're member A), use identity signatures. Those won't change.
• Attestations are portable. A proof of presence created today will verify tomorrow, even if the auth method changed.

What's coming next

Passkey support is solid today. We're exploring:

• Biometric verification as a 2FA option
• Hardware security key support
• Offline identity proofs (SPV-based challenge-response)

None of these will break existing integrations. They're just new ways to prove the same identity.