Overview - moonkey docs

MoonKey sessions allow you to track and manage authenticated user state across your application. Once a user successfully authenticates through any login method (OAuth, email OTP, wallet signature, etc.), MoonKey creates a session that represents their authenticated state.

How sessions work

After successful authentication, MoonKey generates a session and returns session credentials to your application. These credentials are stored in your browser’s IndexedDB and sent with subsequent requests to identify the user. Each session contains:

User information - The user’s ID and associated account details
Authentication factors - The methods used to authenticate (email, OAuth provider, wallet, etc.)
Device information - Details about the device and browser used during login
Session metadata - Creation time, expiration, and other session properties

Session credentials

MoonKey provides two types of session credentials:

Session Token

A standard unique token that doesn’t contain user information. This opaque token must be verified through the MoonKey API on each request. Format: session_abc123xyz... Best for:

Applications requiring real-time session revocation
High-security scenarios where tokens should be opaque
Simple implementation without JWT complexity

Session JWT

A JSON Web Token (JWT) that contains the full session object cryptographically signed using RS256. JWTs can be verified independently using MoonKey’s public keys without making an API call. Format: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... Best for:

Performance-critical applications (no API call needed for verification)
Integration with external systems that rely on JWT standards
Offline or distributed systems

Learn more about the differences and when to use each in the Session Token vs JWT guide.

Basic session lifecycle

1. User authenticates

// User logs in via email OTP, OAuth, or wallet
const { session_token, session_jwt, user } = await authenticate();

2. Session stored automatically

The MoonKey SDK automatically stores session credentials in IndexedDB. No manual storage implementation needed.

3. Session verified on requests

// Backend verifies the session on each request
const { session, user } = await verifySession(sessionToken);

4. Session ends

Sessions expire after a configured duration (default: 7 days) or when explicitly deleted by the user.

Managing sessions

MoonKey provides several API endpoints for session management:

Verify Session - Check if a session is valid and optionally extend its duration
List Sessions - View all active sessions for a user
Delete Session - Revoke a specific session

Session duration

Configure session duration in the MoonKey Dashboard under App Settings. Sessions can last from 1 hour to 30 days (default: 7 days).

Use shorter durations for high-security applications and longer durations for better user experience in low-risk applications.

Using sessions with the React SDK

The MoonKey React SDK handles session management automatically:

import { useMoonKey } from '@moon-key/react-auth';

function App() {
  const { authenticated, user, logout } = useMoonKey();

  if (!authenticated) {
    return <Login />;
  }

  return (
    <div>
      <h1>Welcome, {user.email}</h1>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

The SDK automatically handles:

Session storage in IndexedDB
Session refresh when needed
Session expiration handling
Authentication state management

​How sessions work

​Session credentials

​Session Token

​Session JWT

​Basic session lifecycle

​1. User authenticates

​2. Session stored automatically

​3. Session verified on requests

​4. Session ends

​Managing sessions

​Session duration

​Using sessions with the React SDK

How sessions work

Session credentials

Session Token

Session JWT

Basic session lifecycle

1. User authenticates

2. Session stored automatically

3. Session verified on requests

4. Session ends

Managing sessions

Session duration

Using sessions with the React SDK