Configuration Guide

Advanced configuration options for all MagicDX plugins.

---

Magic-Mail Configuration

Plugin Config

// config/plugins.ts
export default () => ({
  'magic-mail': {
    enabled: true,
    config: {
      // All configuration is done in the admin panel
      // No code-level config needed!
    },
  },
});

Environment Variables (Optional)

# Optional - Encryption key for credentials
ENCRYPTION_KEY=your-32-character-secret-key

# Optional - Base URL for OAuth callbacks
URL=https://yourdomain.com

Admin Panel Settings

Navigate to MagicMail → Settings to configure:

Setting	Description	Default
Default From Email	Fallback sender address	-
Default From Name	Fallback sender name	-
Enable Logging	Log all sent emails	true
Rate Limit Default	Default rate limit per account	500/day

---

Magic-Link Configuration

Plugin Config

// config/plugins.ts
export default () => ({
  'magic-link': {
    enabled: true,
    config: {
      // Context field control for security
      context_whitelist: [], // Only allow these fields (empty = all)
      context_blacklist: ['password', 'secret', 'apiKey', 'token'],
    },
  },
});

Environment Variables

# ===== ENCRYPTION (IMPORTANT!) =====
# Primary encryption key for tokens (32 characters recommended)
MAGIC_LINK_ENCRYPTION_KEY=your-32-character-secret-key-here

# Fallback keys (used if MAGIC_LINK_ENCRYPTION_KEY not set)
# APP_KEYS=key1,key2  # Strapi's default
# API_TOKEN_SALT=your-api-salt

# ===== OTP HASHING =====
# Pepper for OTP code hashing (adds extra security layer)
OTP_PEPPER=your-otp-pepper-secret

# ===== URLs =====
# Frontend URL for magic link redirects
FRONTEND_URL=https://yourfrontend.com

# Base URL for confirmation links
URL=https://yourstrapi.com

Security Note

Never commit .env to version control! Always use strong, unique keys in production.

Generate a secure key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Admin Panel Settings

Navigate to Magic-Link → Settings:

General Settings

Setting	Description	Default
enabled	Enable/disable plugin	true
createUserIfNotExists	Auto-create users on first login	true
expire_period	Token expiration (seconds)	3600
token_length	Token length (20-40)	20
stays_valid	Token reusable after first use	false

Email Settings

Setting	Description	Default
from_name	Sender name	"Your App"
from_email	Sender email	-
object	Email subject	"Your Magic Link"
message_html	HTML email template	Built-in
message_text	Plain text template	Built-in

Security Settings

Setting	Description	Default
rate_limit_enabled	Enable rate limiting	true
rate_limit_max_attempts	Max requests per window	5
rate_limit_window_minutes	Window duration (minutes)	15

MFA Settings (Premium/Advanced)

Setting	Description	License
otp_enabled	Enable Email OTP	Premium
otp_length	OTP code length (4-8)	Premium
otp_expiry	OTP expiration (seconds)	Premium
mfa_require_totp	Require TOTP for login	Advanced
totp_as_primary_auth	Allow TOTP-only login	Advanced

---

Magic-Sessionmanager Configuration

Plugin Config

// config/plugins.ts
export default () => ({
  'magic-sessionmanager': {
    enabled: true,
    config: {
      // Rate limiting for "last seen" updates
      lastSeenRateLimit: 30000, // 30 seconds
      
      // When to mark sessions inactive
      inactivityTimeout: 900000, // 15 minutes
    },
  },
});

Environment Variables

# Encryption key for JWT tokens in database
SESSION_ENCRYPTION_KEY=your-32-byte-base64-key

Generate a key:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Admin Panel Settings

Navigate to Sessions → Settings:

General

Setting	Description	Default
Session Timeout	Inactivity timeout	15 min
Track IP	Store IP addresses	true
Track User Agent	Store browser info	true

Refresh Token Protection

// config/plugins.ts
export default () => ({
  'users-permissions': {
    config: {
      jwtManagement: 'refresh', // Enable refresh tokens
      sessions: {
        accessTokenLifespan: 3600,      // 1 hour
        maxRefreshTokenLifespan: 2592000, // 30 days
      },
    },
  },
  'magic-sessionmanager': {
    enabled: true,
  },
});

Premium/Advanced Settings

Setting	Description	License
IP Geolocation	Show location data	Premium
Threat Detection	Check IP reputation	Advanced
Auto-Blocking	Block suspicious IPs	Advanced
Email Alerts	Send security emails	Advanced
Webhook Notifications	Discord/Slack alerts	Advanced

---

Magic-Mark Configuration

Plugin Config

// config/plugins.ts
export default () => ({
  'magic-mark': {
    enabled: true,
    config: {
      // Maximum bookmarks per user
      maxBookmarksPerUser: 50,
      
      // Enable query history
      enableHistory: true,
      
      // Auto-cleanup old queries (days)
      autoCleanupDays: 90,
    },
  },
});

Admin Panel Settings

Setting	Description	Default
Default Emoji	Default bookmark emoji	📌
Enable Sharing	Allow bookmark sharing	true
Public by Default	New bookmarks public	false

---

🌐 Multi-Plugin Configuration

Complete Setup Example

// config/plugins.ts
export default () => ({
  // Email management for all email needs
  'magic-mail': {
    enabled: true,
  },
  
  // Passwordless authentication
  'magic-link': {
    enabled: true,
    // Uses Magic-Mail automatically when available
  },
  
  // Session tracking
  'magic-sessionmanager': {
    enabled: true,
    config: {
      lastSeenRateLimit: 30000,
      inactivityTimeout: 900000,
    },
  },
  
  // Query bookmarks
  'magic-mark': {
    enabled: true,
    config: {
      maxBookmarksPerUser: 100,
    },
  },
  
  // Refresh token support for sessions
  'users-permissions': {
    config: {
      jwtManagement: 'refresh',
      sessions: {
        accessTokenLifespan: 3600,
        maxRefreshTokenLifespan: 2592000,
      },
    },
  },
});

Environment Variables (.env)

# Magic-Sessionmanager
SESSION_ENCRYPTION_KEY=your-32-byte-base64-key

# Magic-Mail (optional)
ENCRYPTION_KEY=your-32-character-secret-key
URL=https://yourdomain.com

# Email settings (if using Strapi email plugin)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password

---

🔄 Configuration Priority

Settings are loaded in this order (later overrides earlier):

1. Default values - Built-in defaults
2. Plugin config - config/plugins.ts
3. Environment variables - .env file
4. Admin panel - Settings UI

TIP

Admin panel settings override all others, so you can use the UI for most configuration.

---

📖 Next Steps

• Magic-Mail Providers - Email provider setup
• Magic-Link Security - Security configuration
• Magic-Sessionmanager Alerts - Alert setup