Authentication Concepts

Authentication Concepts

The IBEx Wallet API supports 4 authentication modes, each creating a Safe Smart Contract Wallet with a different signer type.

Passkeys (default)

wallet=passkeys — The most secure mode.

The browser generates a WebAuthn key pair (ECDSA P-256). The public key is registered as the signer for a new Safe Smart Contract Wallet (ERC-4337). The private key never leaves the device — it's protected by the device's secure enclave and biometrics.

Flow:

1. GET /v1.2/auth/sign-up → returns credentialRequestOptions
2. Browser calls navigator.credentials.create(options) → user touches biometric
3. POST /v1.2/auth/sign-up with the credential → wallet created

KDF (PIN/Password)

wallet=kdf — For devices without biometric support.

The signer key is derived client-side using Argon2id from a user-chosen PIN or password. The server provides a random salt and KDF parameters. The server never sees the PIN — only the derived public key.

Flow:

1. GET /v1.2/auth/sign-up?wallet=kdf → returns salt, KDF params, challenge
2. Client derives key from PIN + salt using Argon2id
3. Client signs the challenge with derived key
4. POST /v1.2/auth/sign-up with the signature → wallet created

Email (OTP + Encrypted Backup)

wallet=email — Email-first onboarding.

The server sends a 6-digit OTP (30s expiry) to the user's email. The client generates a key pair locally, encrypts the private key with a passphrase, and sends the encrypted blob to the server as a backup. The server never accesses the real key.

Flow:

1. GET /v1.2/auth/sign-up?wallet=email&email=user@example.com → sends OTP, returns challenge
2. User enters OTP → POST /email/recover to verify
3. Client generates key pair, encrypts private key
4. POST /v1.2/auth/sign-up with credential + encrypted backup → wallet created

EOA + EIP-7702

wallet=7702 — Upgrade an existing EOA to a Smart Account.

The user already has an Externally Owned Account (EOA) from MetaMask, WalletConnect, etc. By signing a SIWE-like challenge, they register their EOA as a signer and create an EIP-7702 delegation to SafeEIP7702Proxy.

Flow:

1. GET /v1.2/auth/sign-up?wallet=7702&address=0xCa33... → returns SIWE challenge
2. User signs challenge with their wallet
3. POST /v1.2/auth/sign-up with { wallet: "7702", address, signature, nonce } → delegation created
4. Client broadcasts EIP-7702 authorization transaction on-chain