v1

latestOpenAPI 3.1.02026-07-13143194365.4 KB
auth

Start login with any identity type

Start the login flow by providing any supported identifier:

  • Email: user@example.com
  • Phone: +15551234567 (E.164 format)
  • Handle: @myhandle or myhandle
  • Wallet: 0x1234... (EVM) or Solana address

Returns available authentication methods for the account.

For email/SMS: Use CDP SDK to authenticate, then call /auth/login/complete with the CDP token. For wallet: Sign the challenge message, then call /auth/login/complete with the signature.

Design notes (intentional disclosure):

  • This endpoint returns wallet challenge messages (including full addresses). While this can reveal linked wallets for a handle, those wallets are already visible via public leaderboards. We accept this correlation risk as an explicit product decision.
  • This endpoint also returns the available auth modalities (email/SMS/wallet) for a handle. This can reveal which channels are linked, but we accept this as an explicit product decision given public activity surfaces already imply these modalities.

Completion requirement: When calling /auth/login/complete, clients must send the exact identity_value for the chosen method (full email/phone/address) to disambiguate accounts with multiple identities of the same type.

The login session expires in 10 minutes.

post/v1/auth/login/start

Request body

identifierstring required

User identifier: email, phone (+1...), wallet address (0x...), or handle (@...)

Response

Successful Response

login_tokenstring required

Signed session token (use in login/complete). Contains all session state - no server storage required.

identity_typestring required

Resolved identity type (email, sms, handle, evm, solana)

handlestring nullable

Handle if login was initiated with handle

otp_availableboolean required

Whether OTP-based auth is available (email or SMS)