Authentication

Platform login is a web3 signature exchange for a JWT — and that JWT can never move money.

HEVN separates two completely different kinds of authorization:

	Platform authorization	Money authorization
Credential	HEVN JWT	Signature from a wallet owner key, or from a remote transfer key within its onchain spend allowance
Grants	Contacts, invoices, contracts, virtual account details, KYC, statements, analytics	Transfers and any onchain state change
Issued by	HEVN backend	The signer’s own key, per operation
If leaked	Metadata exposure; funds untouched	Owner key is never exposed (see Privy); a leaked remote transfer key is capped by its onchain allowance and revocable

Platform login flow

HEVN authenticates users the way web3 apps do — by proof of key ownership, not passwords:

1. Sign in with Privy

   The user authenticates with their email or Google account, unlocking their Privy embedded wallet in the session.

2. Sign a login message

   The app asks the Privy wallet to sign a challenge message. Signing a message is free, off-chain, and moves nothing.

3. HEVN verifies the signature

   The backend recovers the signer address from the signature and checks it against the expected Privy address for that identity.

4. HEVN issues its own JWT

   On success, HEVN issues a short-lived JWT scoped to platform features only.

There is no password database to breach and nothing HEVN stores that could be replayed to impersonate a wallet.

What the JWT can and cannot do

The JWT authorizes the HEVN API surface: creating contacts, issuing and paying requests for invoices, generating contracts, requesting virtual account details, reading balances and statements.

The JWT is not a spending credential. Even a fully compromised JWT cannot produce a wallet signature, and the wallet contract only accepts operations signed by an onchain owner. Money movement always terminates in a signature from an authorized key — the owner’s, a teammate’s, or a remote transfer key acting within its allowance.

Remote transfer keys

To let a program pay from your account, you create a remote transfer key in Settings → Remote Transfers. It is not a JWT and it is not a wallet owner. The whitelabel REST API uses developer keys and JWT sessions instead, and rejects X-Api-Key.

Each key has a spender wallet of its own: a smart wallet owned by a signer HEVN derives from the key. Its spending ability is governed onchain, by the same standard as teammate access: you sign a SpendPermission from your wallet naming that spender, with an explicit allowance and period.

The consequences of this design:

• Without a spend permission, a key cannot move a single cent. A transfer is a user operation from the spender wallet, and the SpendPermissionManager contract accepts it only within the granted allowance.
• A leaked key is capped and revocable. The worst case is bounded by the remaining onchain allowance for the current period. Deleting the key in the app revokes the permission onchain and kills the key in one action.
• Your own key is never involved. No key material leaves the Privy layer; the remote transfer key is a separate identity with its own, strictly smaller, rights.

Remote transfers are for advanced use. For everyday payments, use the app or the HEVN assistant, which only files transfer requests that you approve. Treat keys as secrets: one per integration, the smallest allowance that works, stored outside your codebase.