# Overview

MoonPay Wallets 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, MoonPay Wallets handles the complexity of authentication so you can focus on building your product.

## Supported authentication methods

MoonPay Wallets offers the following authentication methods:

### Passwordless authentication

* **[Email OTP](/authentication/user-authentication/authentication-methods/email)**: One-time passcode sent to a user's email address for passwordless login

### Social login (OAuth)

* **[OAuth](/authentication/user-authentication/authentication-methods/oauth)**: Social login with:
  * [Google](/authentication/user-authentication/authentication-methods/oauth/google)
  * Apple
  * Additional providers coming soon

After login, users protect their embedded wallet with a **[passkey](/authentication/user-authentication/passkeys)**: passkeys encrypt wallet key material and prove the user is physically present for sensitive operations, rather than acting as a standalone login method.

## Flexible authentication flows

MoonPay Wallets 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 MoonPay Wallets authentication methods create a common user object. Regardless of how a user authenticates, whether through email OTP or OAuth, 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 or a Google/Apple account. This unified approach simplifies user management and enables seamless multi-method authentication.

## Getting started

### Using the React SDK

The easiest way to integrate MoonPay Wallets authentication is with the React SDK, which provides pre-built UI components and hooks:

```typescript
import { MoonXProvider, useLoginWithEmail } from '@moon-x/react-sdk';

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

function App() {
  return (
    <MoonXProvider publishableKey="your_publishable_key">
      <LoginButton />
    </MoonXProvider>
  );
}
```

[Get started with the React SDK →](/get-started/frontend-sdks/react/installation)

### Using the REST API

For more control or custom integrations, use the REST API directly:

```bash
# Send email OTP. captcha_token is required and is minted by the MoonPay Wallets
# authentication iframe, so the SDKs attach it for you. See the email
# authentication guide if you are calling this without the iframe.
curl -X POST "https://x-api.moonpay.com/v0/sdk/wallet/email/begin" \
  -H "Authorization: PublicToken moon_pk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "captcha_token": "P1_eyJ0eXAiOiJKV1Qi..."}'

# Verify OTP and create session
curl -X POST "https://x-api.moonpay.com/v0/sdk/wallet/email/verify" \
  -H "Authorization: PublicToken moon_pk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "code": "123456"
  }'
```

A successful verification returns the session token bundle: a short-lived access token (1 hour), an identity token (10 hours), and a rotating refresh token (30 days), along with the user object.

[Get started with the REST API →](/get-started/rest-api/setup)

## Configuration and setup

### Dashboard configuration

Configure your authentication methods in the [MoonPay Wallets Dashboard](https://dashboard.moonx-dev.com):

1. **[Configure login methods](/get-started/dashboard/login-methods)** - Enable email OTP and OAuth login
2. **[Set up OAuth providers](/get-started/dashboard/login-methods#social-providers-oauth)** - Configure Google and Apple
3. **[Whitelist domains and redirect URLs](/get-started/domain-whitelisting)** - Set up secure redirect destinations for OAuth flows

### SDK integration

<CardGroup cols={3}>
  <Card title="React SDK" icon="react" href="/get-started/frontend-sdks/react/installation">
    Pre-built components and hooks for React and Next.js
  </Card>

  <Card title="REST API" icon="code" href="/get-started/rest-api/setup">
    Direct API access for custom integrations
  </Card>

  <Card title="Node.js SDK" icon="node" href="/authentication/user-authentication/sessions/backend-verification">
    Server-side token verification with @moon-x/node-sdk
  </Card>
</CardGroup>

## 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