Authentication
LiveHow HeartBadge member security gates affect integrations and reward flows.
HeartBadge uses member security readiness to decide which account actions are available. Integrations should treat readiness as an API state, not as a detail to infer from a specific login method.
Member readiness gates
| Gate | Requirement | Developer impact |
|---|---|---|
| Core security | Verified email plus passkey or authenticator 2FA | Required before member sends and cashout eligibility |
| Solana link | Authenticator 2FA | Passkey alone is not sufficient for Solana destination linking |
| Cashout | Core security plus at least one linked destination | Destination state determines available cashout routes |
| Hardened | Passkey and 2FA plus Solana and HandCash destinations | Best state for high-value accounts and broadest destination support |
Do not hard-code login methods
Programs should not assume a member used a particular authentication method. A member may satisfy core security with a passkey or authenticator 2FA. Future proof integrations by checking readiness fields and action eligibility instead of parsing session details.
Action confirmation
Sensitive actions may require an additional challenge at the time of the action. Depending on the member's setup, that challenge can be a passkey prompt or an authenticator code. Solana destination linking is the exception: it specifically requires authenticator 2FA.
Recommended integration behavior
- Read readiness from the API. Use member status and action eligibility responses instead of recreating security logic.
- Surface the next action. If a member cannot complete a flow, direct them to Vault Account Security rather than naming a generic error.
- Separate send from cashout. Member-to-member sends need core security and transferable balance. Cashout also needs a linked destination.
- Handle destination-specific gates. Solana requires authenticator 2FA; HandCash connection follows the destination connection flow.
Member docs
The member-facing model is documented in Account Security, Passkeys, Two-Factor Auth, and Linked Destinations.