emblem-auth-sdk

Official TypeScript SDK for Emblem Vault authentication.

Installation

npm install emblem-auth-sdk
# or
yarn add emblem-auth-sdk

Quick Start

import { EmblemAuthSDK } from 'emblem-auth-sdk';

// Minimal setup - only appId is required
const auth = new EmblemAuthSDK({
  appId: 'your-app-id',
  onSuccess: (session) => {
    console.log('Authenticated!', session);
  },
  onError: (error) => {
    console.error('Auth failed:', error);
  }
});

// Open authentication modal
auth.openAuthModal();

// Get current session
const session = auth.getSession();

// Use JWT for API calls
fetch('https://api.emblemvault.ai/protected-endpoint', {
  headers: {
    'Authorization': `Bearer ${session.authToken}`
  }
});

Features

• 🔐 Multiple Auth Methods - Wallet (EVM, Solana, Hedera) and OAuth (Twitter, Google)
• 🔑 JWT-based Sessions - Secure token management with auto-refresh
• 💾 Session Persistence - Stay logged in across page reloads (enabled by default)
• 🎨 Flexible UI - Iframe or popup modal modes
• 📦 TypeScript - Full type definitions included
• 🌐 Browser & Node - Works in browsers and Node.js environments
• ⚡ Lightweight - < 15KB minified and gzipped

API Reference

Constructor

new EmblemAuthSDK(config: EmblemAuthConfig)

Config Options

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | appId | string | ✅ | - | Your application ID | | apiUrl | string | ❌ | https://api.emblemvault.ai | Emblem Vault API URL | | modalUrl | string | ❌ | https://auth.emblemvault.ai/connect | Auth modal URL | | modalMode | 'iframe' | 'popup' | 'auto' | ❌ | 'auto' | Modal display mode | | persistSession | boolean | ❌ | true | Persist session to localStorage (stay logged in) | | onSuccess | (session) => void | ❌ | - | Success callback | | onError | (error) => void | ❌ | - | Error callback |

Methods

openAuthModal(): Promise<void>

Opens the authentication modal for users to sign in.

getSession(): AuthSession | null

Returns the current authentication session.

refreshSession(): Promise<AuthSession | null>

Manually refreshes the authentication token.

authenticateWallet(params): Promise<AuthSession | null>

Programmatically authenticate with wallet signature.

getVaultInfo(): Promise<VaultInfo>

Retrieves information about the user's vault. Caches the result for the session duration.

const vaultInfo = await auth.getVaultInfo();
console.log(vaultInfo.vaultId);
console.log(vaultInfo.evmAddress);

getVaultApiKey(): Promise<string>

Retrieves or generates the vault API key.

logout(): void

Clears the current session.

on(event, handler): void

Subscribe to authentication events.

off(event, handler): void

Unsubscribe from authentication events.

Events

• session - Fired when session is established or updated
• sessionExpired - Session has expired
• sessionRefreshed - Session was refreshed
• sessionWillRefresh - Session will refresh soon
• authError - Authentication error occurred

Session Persistence

By default, sessions are persisted to localStorage, allowing users to stay logged in across page reloads and browser sessions. This follows the industry-standard "stay logged in" behavior.

// Default behavior - sessions are persisted
const auth = new EmblemAuthSDK({
  appId: 'your-app-id'
});

// Sessions will automatically restore on page load
const session = auth.getSession(); // Returns persisted session if valid

// To disable persistence (session only lasts until page closes)
const auth = new EmblemAuthSDK({
  appId: 'your-app-id',
  persistSession: false
});

Notes:

• Sessions are stored with the key emblem_session_{appId}
• Expired sessions are automatically cleared on load
• Calling logout() clears the persisted session
• Works gracefully in private browsing mode (falls back to memory-only)

Types

VaultInfo

interface VaultInfo {
  vaultId: string;
  evmAddress?: string;
  solanaAddress?: string;
  hederaAccountId?: string;
  createdAt?: string;
  metadata?: Record<string, any>;
}

CDN Usage

<script src="https://unpkg.com/emblem-auth-sdk@latest/dist/emblem-auth.min.js"></script>
<script>
  // Only appId is required - apiUrl and modalUrl have production defaults
  const auth = new EmblemAuth.EmblemAuthSDK({
    appId: 'your-app-id'
  });

  auth.openAuthModal();
</script>

Alternative CDNs:

• jsDelivr: https://cdn.jsdelivr.net/npm/emblem-auth-sdk@latest/dist/emblem-auth.min.js
• unpkg (specific version): https://unpkg.com/[email protected]/dist/emblem-auth.min.js

License

MIT