Authentication

n8n MCP Bridge offers three authentication methods to suit your security and convenience preferences:

• OAuth (Google, GitHub) - Quick social login
• Magic Link - Passwordless email authentication
• OTP Codes - Secure 6-digit verification codes

Sign In Methods

Method 1: OAuth (Social Login)

Sign in with your existing Google or GitHub account.

Using Google:

1. Navigate to http://localhost:3000/auth/signin
2. Click Continue with Google
3. Select your Google account
4. Authorize the application
5. You'll be redirected to the dashboard

Using GitHub:

1. Navigate to http://localhost:3000/auth/signin
2. Click Continue with GitHub
3. Authorize the application
4. You'll be redirected to the dashboard

Method 2: Magic Link

Receive a sign-in link via email (no password needed).

1. Navigate to http://localhost:3000/auth/signin
2. Ensure Magic Link is selected (default)
3. Enter your email address
4. Click Send Magic Link
5. Check your email for the sign-in link
6. Click the link to sign in
7. You'll be automatically redirected to the dashboard

Link expires in 15 minutes for security.

Method 3: OTP (Verification Code)

Receive a 6-digit code via email for enhanced security.

1. Navigate to http://localhost:3000/auth/signin
2. Click Verification Code toggle
3. Enter your email address
4. Click Send Code
5. Check your email for the 6-digit code
6. Enter the code on the sign-in page
7. Click Sign In
8. You'll be redirected to the dashboard

Code expires in 10 minutes for security.

Note: If you don't receive the code, check your spam folder or click "Send a new code" after waiting a minute.

First-Time Setup

After signing in for the first time:

1. Your user account is automatically created
2. You're assigned the USER role by default
3. You're redirected to the dashboard at /dashboard

Session Management

Session Duration

• Sessions are valid for 30 days by default
• Sessions are stored securely using JWT tokens
• Encrypted session data is stored in the database

Sign Out

To sign out:

1. Click your profile icon in the top-right corner
2. Select Sign Out
3. You'll be redirected to the homepage

Your session will be invalidated and removed from the database.

Account Management

Linked Accounts

You can link multiple OAuth providers to the same account:

1. Sign in with your primary provider (e.g., Google)
2. Go to account settings
3. Link additional providers (e.g., GitHub)

This allows you to sign in using any linked provider.

Account Information

View your account details in the dashboard:

• Email: Your primary email from OAuth provider
• Name: Your display name
• Provider: Which OAuth provider(s) you've used
• Role: Your user role (USER or ADMIN)

Email Configuration (for Magic Link & OTP)

To use Magic Link or OTP authentication, configure SMTP in your .env file:

SMTP_HOST="smtp.gmail.com"          # Your SMTP server
SMTP_PORT="587"                      # 587 for TLS, 465 for SSL
SMTP_SECURE="false"                  # true for SSL, false for TLS
SMTP_USER="your-email@gmail.com"    # Your email address
SMTP_PASSWORD="your-app-password"    # App-specific password
SMTP_FROM="noreply@example.com"      # From address
SMTP_FROM_NAME="n8n MCP Bridge"      # From name

Warning: For Gmail, you must use an App Password, not your regular password. 2FA must be enabled to create app passwords.

After updating .env, restart the application:

task dev

Security

Authentication Methods Security

OAuth (Google, GitHub)

• Uses industry-standard OAuth 2.0 Authorization Code Flow with PKCE
• No passwords stored or managed by the application
• Delegated authentication to trusted providers

Magic Link

• One-time use links with 15-minute expiry
• Links are invalidated after first use
• Secure token validation via database

OTP Codes

• 6-digit numeric codes (1 million combinations)
• 10-minute expiry window
• One-time use only
• Rate limited to 10 attempts per minute

Data Privacy

• No passwords stored: All authentication is passwordless
• Minimal data collection: Only email and name are stored
• Encrypted sessions: Session tokens are encrypted with AES-256
• Secure cookies: HTTP-only, secure cookies for session management
• Rate limiting: Prevents brute-force attacks (10 requests/minute)

Role-Based Access

USER Role

Default role for all new users. Can:

• Create and manage their own n8n connections
• Create and manage MCP API keys
• Create and manage OAuth clients
• Use the memory system
• View usage analytics

ADMIN Role

Administrative role with additional permissions:

• Access to admin dashboard
• View all users and their connections
• Manage system settings
• View system-wide analytics

To grant admin access, update the user's role in the database:

UPDATE "user"
SET role = 'ADMIN'
WHERE email = 'user@example.com';

Troubleshooting

Email Not Received (Magic Link / OTP)

If you don't receive the email:

1. Check spam/junk folder - Email providers may flag authentication emails
2. Verify SMTP configuration - Ensure all SMTP_* variables are set in .env
3. Check Docker logs - Look for email sending errors: docker compose logs app | grep -i smtp
4. Restart application - SMTP settings require restart: task dev
5. Test SMTP credentials - Verify login works at your email provider
6. Wait for rate limit - If you tried many times, wait 1-2 minutes

OAuth Error: Redirect URI Mismatch

If you see this error:

1. Verify redirect URI in OAuth provider settings
2. For Google: Should be http://localhost:3000/api/auth/callback/google
3. For GitHub: Should be http://localhost:3000/api/auth/callback/github
4. Ensure exact match including protocol and port

OAuth Error: Invalid Client

If authentication fails with "invalid client":

1. Check GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env
2. Verify credentials are correct in OAuth provider console
3. Restart the application: task dev

OTP Code Not Working

If your verification code is rejected:

1. Check expiry - Codes expire after 10 minutes
2. Verify code - Ensure all 6 digits are entered correctly
3. Rate limit - After 10 failed attempts, wait 1 minute
4. Request new code - Click "Send a new code" button
5. Check email - Use the most recent code received

Session Expired

If your session expires:

1. Sign in again using any authentication method
2. Your data and settings are preserved
3. Sessions last 7 days by default

Next Steps

Now that you're authenticated, create your first API key:

Create Your First API Key →