Skip to main content

​
Authentication with MoonKey

MoonKey provides a comprehensive authentication system that supports multiple login methods, giving your users flexibility while maintaining security. Whether you’re building for web3-native users or traditional audiences, MoonKey handles the complexity of authentication so you can focus on building your product.

​
Supported authentication methods

MoonKey offers a variety of authentication methods:

​
Passwordless authentication

  • Email OTP: One-time passcode sent to a user’s email address for passwordless login

​
Social login (OAuth)

  • OAuth: Social login with popular providers
    • Google
    • Apple
    • Additional providers coming soon

​
Web3 authentication

  • Wallet login: External wallet authentication using:
    • Sign-In With Ethereum (SIWE) for Ethereum and EVM-compatible chains
    • Sign-In With Solana (SIWS) for Solana

​
Flexible authentication flows

MoonKey allows you to configure authentication methods in two ways:
  1. Upfront login methods: Users can authenticate directly with these methods during initial login
  2. Linked accounts: Users can connect additional authentication methods to their profile after initial login
This flexibility lets users authenticate with their preferred method while maintaining a single unified identity across all connected accounts.

​
The unified user object

All of MoonKey’s authentication methods create a common user object. Regardless of how a user authenticates—whether through email, OAuth, or a wallet—they’re represented by the same user structure. The user object contains:
  • A unique user ID
  • All linked accounts (emails, wallets, OAuth providers)
  • Authentication factors and verification status
  • User metadata and profile information
A user is a user, whether they’ve authenticated with an email, Google account, or Ethereum wallet. This unified approach simplifies user management and enables seamless multi-method authentication.

​
Getting started

​
Using the React SDK

The easiest way to integrate MoonKey authentication is with the React SDK, which provides pre-built UI components and hooks: 
import { MoonKeyProvider, useLoginWithEmail } from '@moon-key/react-auth';

function LoginButton() {
  const { loginWithEmail } = useLoginWithEmail();
  
  return (
    <button onClick={() => loginWithEmail({ email: 'user@example.com' })}>
      Login with Email
    </button>
  );
}

function App() {
  return (
    <MoonKeyProvider publishableKey="your_publishable_key">
      <LoginButton />
    </MoonKeyProvider>
  );
}
Get started with the React SDK →

​
Using the REST API

For more control or custom integrations, use the REST API directly: 
# Send email OTP
curl -X POST "https://api.moonkey.fun/v1/auth/otps/email/send" \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

# Verify OTP and create session
curl -X POST "https://api.moonkey.fun/v1/auth/otps/verify" \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "code": "123456",
    "session_expires_in": 10080
  }'
Get started with the REST API →

​
Configuration and setup

​
Dashboard configuration

Configure your authentication methods in the MoonKey Dashboard:
  1. Configure login methods - Enable email, OAuth, and wallet authentication
  2. Set up OAuth providers - Configure Google, Apple, and other social providers
  3. Manage redirect URLs - Set up secure redirect destinations for OAuth flows

​
SDK integration

React SDK

Pre-built components and hooks for React and Next.js

REST API

Direct API access for custom integrations

Node.js SDK

Server-side authentication and user management

​
Best practices

​
Security

  • Use HTTPS only - Always transmit authentication credentials over secure connections
  • Implement rate limiting - Protect against brute force attacks on OTP verification
  • Validate sessions server-side - Never trust client-side authentication alone

​
User experience

  • Offer multiple methods - Let users choose their preferred authentication method
  • Streamline the flow - Minimize steps between login initiation and success
  • Handle errors gracefully - Provide clear error messages and recovery options

​
Implementation

  • Test thoroughly - Verify all authentication flows work correctly
  • Handle edge cases - Account for expired sessions, network failures, and invalid codes
  • Keep credentials secure - Store session tokens in IndexedDB