ComfyUI/FRONTEND_AUTH_GUIDE.md

ComfyUI Frontend Authentication Guide

Overview

When API key authentication is enabled, the ComfyUI frontend will automatically require users to log in with the API key before accessing the interface.

How It Works

1. Automatic Redirection: When you access ComfyUI with authentication enabled, you'll be automatically redirected to a login page if no valid API key is stored.

2. API Key Storage: After successful login, your API key is stored in your browser (localStorage or sessionStorage) depending on your "Remember me" choice.

3. Automatic Injection: The API key is automatically added to all API requests via the Authorization: Bearer <key> header.

4. Session Management:

   • Remember me (checked): API key stored in localStorage (persists across browser sessions)
   • Remember me (unchecked): API key stored in sessionStorage (cleared when browser closes)

Using the Frontend with Authentication

First Time Access

1. Start ComfyUI with an API key:

   python main.py --api-key "your-secret-key-123"
   

2. Open your browser and navigate to http://localhost:8188

3. You'll be presented with a login page

4. Enter your API key and click "Login"

5. Choose whether to remember your login (recommended for personal devices only)

Login Page Features

• Show API Key: Toggle to view the key you're entering
• Remember Me: Keep your session active across browser restarts
• Auto-validation: The system validates your key before storing it

Logging Out

To log out and clear your stored API key:

Option 1: JavaScript Console

comfyuiLogout()

Option 2: Browser DevTools

1. Open DevTools (F12)
2. Go to Application > Storage
3. Clear localStorage and sessionStorage
4. Refresh the page

Option 3: Manual URL Navigate to: http://localhost:8188/auth_login.html

Security Considerations

For Personal Use

• ✅ Enable "Remember me" for convenience
• ✅ Use strong, unique API keys
• ✅ Keep your browser updated

For Shared/Public Computers

• ❌ DO NOT enable "Remember me"
• ✅ Always log out when finished
• ✅ Clear browser data after use
• ✅ Consider using a private/incognito window

For Production Deployments

• ✅ Always use HTTPS (combine with --tls-keyfile and --tls-certfile)
• ✅ Use strong, randomly generated API keys
• ✅ Rotate keys regularly
• ✅ Monitor access logs for unauthorized attempts
• ✅ Consider using additional security layers (VPN, firewall, etc.)

Troubleshooting

"Invalid API Key" Error

Problem: Login fails with invalid API key message

Solutions:

1. Verify you're using the correct API key
2. Check for extra spaces or newlines
3. Ensure the server was started with the same API key
4. Check server logs for authentication attempts

Automatic Logout

Problem: Frequently logged out automatically

Possible Causes:

1. API key changed on server (restart required)
2. Browser cleared storage automatically
3. "Remember me" was not checked
4. Session expired (if using sessionStorage)

Solution: Check "Remember me" when logging in

Login Page Not Showing

Problem: Can't access login page

Possible Causes:

1. Authentication not enabled (no --api-key argument)
2. Browser cached old version

Solution:

1. Hard refresh the page (Ctrl+Shift+R or Cmd+Shift+R)
2. Clear browser cache
3. Try accessing directly: http://localhost:8188/auth_login.html

API Requests Still Failing

Problem: Some API requests return 401 after login

Solutions:

1. Check browser console for errors
2. Verify API key is stored: Open DevTools > Application > Storage
3. Try logging out and back in
4. Clear all browser data and try again

Advanced Usage

Programmatic Access with Frontend

If you need to access the API programmatically while using the frontend:

// Get the stored API key
const apiKey = localStorage.getItem('comfyui_api_key') || 
               sessionStorage.getItem('comfyui_api_key');

// Make authenticated requests
fetch('/api/system_stats', {
    headers: {
        'Authorization': `Bearer ${apiKey}`
    }
}).then(r => r.json()).then(console.log);

Custom Frontend Integration

If you're building a custom frontend, you can use the same mechanism:

1. Login Flow:

   // Validate API key
   const response = await fetch('/health', {
       headers: {
           'Authorization': `Bearer ${apiKey}`
       }
   });
   
   if (response.ok) {
       // Store the key
       localStorage.setItem('comfyui_api_key', apiKey);
   }
   

2. Request Interceptor:

   // Add to all requests
   const apiKey = localStorage.getItem('comfyui_api_key');
   
   fetch(url, {
       headers: {
           'Authorization': `Bearer ${apiKey}`,
           ...otherHeaders
       }
   });
   

3. Handle 401 Responses:

   if (response.status === 401) {
       // Clear stored key and redirect to login
       localStorage.removeItem('comfyui_api_key');
       window.location.href = '/auth_login.html';
   }
   

API Endpoints Reference

Public Endpoints (No Authentication Required)

• GET / - Main page (with auth script injected)
• GET /health - Health check
• GET /auth_login.html - Login page
• GET /auth_inject.js - Auth injection script
• GET /ws - WebSocket connection
• Static files (.js, .css, .html, etc.)

Protected Endpoints (Authentication Required)

• All /api/* endpoints
• All /internal/* endpoints
• Most other API endpoints

Browser Compatibility

The authentication system works with all modern browsers:

• ✅ Chrome/Edge 90+
• ✅ Firefox 88+
• ✅ Safari 14+
• ✅ Opera 76+

FAQs

Q: Can I use ComfyUI without authentication?
A: Yes! Simply start ComfyUI without the --api-key argument.

Q: Can I change the API key without losing my workflows?
A: Yes, workflows are stored separately. Just update the key on the server and re-login.

Q: Is my API key secure?
A: The key is stored in browser storage and sent over HTTPS (if configured). For maximum security, use HTTPS and strong keys.

Q: Can multiple users use different API keys?
A: Currently, the system supports a single API key. For multi-user scenarios, each user must use the same key.

Q: What happens if I forget my API key?
A: Check your server startup command or the file specified in --api-key-file.

Support

For issues or questions:

1. Check the server logs
2. Review browser console for errors
3. Refer to the main authentication documentation: API_AUTHENTICATION.md
4. Check the quick start guide: QUICK_START_AUTH.md