Skip to main content
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:

​
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