Authorization Mode - DeepWiki-Open

Authorization mode provides access control for your DeepWiki-Open instance by requiring users to enter a secret authorization code before generating wikis. This is essential for production deployments, shared environments, or when you want to control who can generate documentation from repositories.

What is Authorization Mode?

Authorization mode is a simple but effective security feature that:

Frontend Protection

Users must enter an authorization code in the web interface

API Security

All API requests must include the authorization code

Resource Control

Prevents unauthorized usage of AI provider quotas

Access Logging

Tracks and logs authentication attempts

When to Use Authorization Mode

Recommended Scenarios

Production Deployments

Always enable authorization mode in production environments:

Public-facing instances
Shared hosting environments
Corporate deployments
Any instance accessible from the internet

Benefits:

Prevents unauthorized access to AI providers
Controls API usage and costs
Maintains audit trail of access

Team Collaboration

Shared development environments:

Team wikis for private repositories
Collaborative documentation projects
Educational environments
Demo instances with controlled access

Benefits:

Ensures only authorized team members can generate docs
Prevents accidental quota exhaustion
Maintains consistent access control

Cost Management

AI provider quota protection:

Limited API budgets
Pay-per-use providers
Rate-limited accounts
Enterprise cost control

Benefits:

Prevents unexpected charges
Controls usage patterns
Enables usage tracking per authorization

When NOT to Use Authorization Mode

Authorization mode can be disabled for:

Local development instances
Personal single-user setups
Internal networks with existing security
Testing and experimentation environments

Configuration

Environment Variables

Configure authorization mode using these environment variables: Enable or disable authorization mode. Secret authorization code required for access.

Basic Configuration

Set Environment Variables

Add to your .env file:

# Enable authorization mode
DEEPWIKI_AUTH_MODE=true

# Set your secret authorization code
DEEPWIKI_AUTH_CODE=your-secure-code-here

Choose a strong, unique authorization code. Avoid common passwords or easily guessable codes.

Restart Services

Authorization mode requires a full restart:

Docker
Manual Setup

# Stop containers
docker-compose down

# Start with new configuration
docker-compose up -d

# Verify authorization mode is enabled
docker-compose logs api | grep "Authorization"

Verify Configuration

Check authorization status:

curl -X GET "http://localhost:8001/auth/status"

Expected response:

{
  "auth_required": true
}

Server logs should show: “Authorization mode: ENABLED”

Advanced Configuration

# Production authorization settings
DEEPWIKI_AUTH_MODE=true
DEEPWIKI_AUTH_CODE=prod-secure-auth-2024-XYZ789

# Additional security settings
NODE_ENV=production
LOG_LEVEL=WARNING
LOG_SENSITIVE_DATA=false

# Server configuration
SERVER_BASE_URL=https://deepwiki.yourdomain.com
PORT=8001

Frontend Usage

Authorization Code Input

When authorization mode is enabled, users see an authorization code input field:

Authorization Required

This code is required to generate wikis

User Experience Flow

User Access

User visits the DeepWiki-Open interface and sees:

Normal repository URL input
Authorization code field (when mode is enabled)
Clear indication that authorization is required

Code Entry

User enters the authorization code:

Code is masked (password field)
Real-time validation (optional)
Clear error messages for invalid codes

Wiki Generation

After successful authorization:

Normal wiki generation flow continues
Code is included in API requests automatically
User doesn’t need to re-enter code for the session

Frontend Implementation

The frontend automatically detects authorization mode:

// Authorization status check
const checkAuthStatus = async () => {
  const response = await fetch('/api/auth/status');
  const { auth_required } = await response.json();
  
  if (auth_required) {
    // Show authorization code input
    setShowAuthInput(true);
  }
};

// Authorization validation
const validateAuthCode = async (code) => {
  const response = await fetch('/api/auth/validate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ code })
  });
  
  const { success } = await response.json();
  return success;
};

API Usage

Including Authorization Codes

All API requests must include the authorization code when mode is enabled:

curl -X POST "http://localhost:8001/wiki/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/facebook/react",
    "model_provider": "google",
    "authorization_code": "your-secure-code-here"
  }'

Authorization Validation Endpoint

Test authorization codes before use:

curl -X POST "http://localhost:8001/auth/validate" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "your-secure-code-here"
  }'

{
  "success": true
}

Security Considerations

Authorization Code Security

Code Generation Best Practices

Strong authorization codes:

# Good examples
team-wiki-2024-XRT789-secure
prod-deepwiki-auth-94KL23P
company-docs-access-2024-QW45

# Avoid these
123456
password
admin
test
deepwiki

Generation methods:

# Generate random codes
openssl rand -hex 16
# Output: a3f7c9e2b4d8f6a1c5e9b7d3f8a2c6e4

# Generate pronounceable codes
openssl rand -base64 12 | tr -d "=+/" | cut -c1-16
# Output: kH7mP9qR3sL4wX8t

# Custom format
echo "wiki-$(date +%Y)-$(openssl rand -hex 4)"
# Output: wiki-2024-7a8b9c2d

Code Storage and Rotation

Secure storage:

Store codes in environment variables, not source code
Use secrets management in production (AWS Secrets Manager, Azure Key Vault)
Restrict file permissions on .env files (chmod 600)
Never commit authorization codes to version control

Regular rotation:

# Rotation schedule
# - Development: Monthly
# - Staging: Bi-weekly  
# - Production: Weekly or after security incidents

# Rotation process:
# 1. Generate new authorization code
# 2. Test with new code in staging
# 3. Update production environment variables
# 4. Restart services
# 5. Notify authorized users
# 6. Monitor for authentication failures

Code management:

# Environment-specific codes
DEEPWIKI_AUTH_CODE_DEV=dev-auth-code-123
DEEPWIKI_AUTH_CODE_STAGING=staging-auth-456
DEEPWIKI_AUTH_CODE_PROD=prod-auth-789

# Use deployment scripts to select appropriate code
export DEEPWIKI_AUTH_CODE=${DEEPWIKI_AUTH_CODE_PROD}

Network Security

HTTPS requirement:

# Always use HTTPS in production
server {
    listen 443 ssl;
    server_name deepwiki.yourdomain.com;
    
    # SSL configuration
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    
    location / {
        proxy_pass http://localhost:8001;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name deepwiki.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

Access restrictions:

# Firewall rules for additional security
# Only allow specific IPs to access API directly
iptables -A INPUT -p tcp --dport 8001 -s 192.168.1.0/24 -j ACCEPT
iptables -A INPUT -p tcp --dport 8001 -j DROP

# Allow HTTPS from anywhere (proxied)
iptables -A INPUT -p tcp --dport 443 -j ACCEPT

Attack Prevention

Authorization mode provides basic access control but is not a complete security solution. Consider additional measures:

Rate limiting to prevent brute force attacks
IP whitelisting for sensitive environments
Web Application Firewall (WAF) for production
Regular security audits and monitoring
Multi-factor authentication for critical deployments

Rate limiting example:

# Basic rate limiting implementation
from collections import defaultdict
from time import time

auth_attempts = defaultdict(list)
MAX_ATTEMPTS = 5
WINDOW_SECONDS = 300  # 5 minutes

def check_rate_limit(ip_address):
    now = time()
    attempts = auth_attempts[ip_address]
    
    # Remove old attempts
    attempts[:] = [t for t in attempts if now - t < WINDOW_SECONDS]
    
    if len(attempts) >= MAX_ATTEMPTS:
        return False  # Rate limited
    
    attempts.append(now)
    return True

Troubleshooting

Common Issues

Authorization Code Not Working

Symptoms:

“Invalid authorization code” errors
Authentication consistently fails
API returns 401 status codes

Solutions:

Verify environment variables:

echo "Auth Mode: $DEEPWIKI_AUTH_MODE"
echo "Auth Code: $DEEPWIKI_AUTH_CODE"

Check code formatting:

# Ensure no extra spaces or characters
export DEEPWIKI_AUTH_CODE=$(echo "$DEEPWIKI_AUTH_CODE" | xargs)

Restart services completely:

# Kill all processes
pkill -f "python -m api.main"
pkill -f "npm"

# Wait a moment, then restart
sleep 2
python -m api.main &
npm run dev &

Test with curl:

curl -X POST "http://localhost:8001/auth/validate" \
  -H "Content-Type: application/json" \
  -d '{"code": "your-exact-code-here"}'

Frontend Not Showing Auth Input

Symptoms:

Authorization mode enabled but no auth input field
Frontend behaves as if authorization is disabled
No indication that auth is required

Solutions:

Check API status endpoint:

curl -X GET "http://localhost:8001/auth/status"

Verify frontend API connection:

// Check in browser console
fetch('/api/auth/status')
  .then(r => r.json())
  .then(console.log);

Clear browser cache:

# Or use browser dev tools:
# Application > Storage > Clear Site Data

Check Next.js API routes:

# Verify routes exist
ls -la src/app/api/auth/

API Forwarding Issues

Symptoms:

Frontend shows auth required but validation fails
Network errors in browser console
Proxy/forwarding failures

Solutions:

Check SERVER_BASE_URL:

echo "Server URL: $SERVER_BASE_URL"
# Should match your backend API location

Test direct API access:

# Test backend directly
curl -X GET "http://localhost:8001/auth/status"

# Test frontend proxy
curl -X GET "http://localhost:3000/api/auth/status"

Verify port configuration:

# Backend should be running on PORT
netstat -tulpn | grep :8001

# Frontend should be running on 3000
netstat -tulpn | grep :3000

Debugging Steps

Check Configuration

# Verify environment variables are loaded
python -c "
import os
from dotenv import load_dotenv
load_dotenv()

print('Auth Mode:', os.getenv('DEEPWIKI_AUTH_MODE'))
print('Auth Code Set:', bool(os.getenv('DEEPWIKI_AUTH_CODE')))
print('Server URL:', os.getenv('SERVER_BASE_URL'))
"

Test API Endpoints

# Test status endpoint
curl -v -X GET "http://localhost:8001/auth/status"

# Test validation endpoint
curl -v -X POST "http://localhost:8001/auth/validate" \
  -H "Content-Type: application/json" \
  -d '{"code": "test-code"}'

# Test wiki generation (should require auth)
curl -v -X POST "http://localhost:8001/wiki/generate" \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "https://github.com/octocat/Hello-World", "model_provider": "google"}'

Check Logs

# Backend logs
tail -f api/logs/application.log

# Look for:
# - "Authorization mode: ENABLED/DISABLED"
# - Authentication attempt logs
# - Error messages related to auth

Frontend Debugging

// In browser console
// Check authorization status
fetch('/api/auth/status').then(r => r.json()).then(console.log);

// Test validation
fetch('/api/auth/validate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ code: 'test-code' })
}).then(r => r.json()).then(console.log);

Production Deployment

Docker Configuration

services:
  deepwiki-api:
    build: .
    environment:
      # Authorization configuration
      - DEEPWIKI_AUTH_MODE=true
      - DEEPWIKI_AUTH_CODE=${DEEPWIKI_AUTH_CODE}
      
      # API keys
      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      
      # Server configuration
      - PORT=8001
      - SERVER_BASE_URL=https://api.deepwiki.yourdomain.com
      
      # Security settings
      - NODE_ENV=production
      - LOG_LEVEL=WARNING
    ports:
      - "8001:8001"
    restart: unless-stopped
    
  deepwiki-frontend:
    build:
      context: .
      dockerfile: Dockerfile.frontend
    environment:
      - SERVER_BASE_URL=https://api.deepwiki.yourdomain.com
      - NEXT_PUBLIC_API_URL=https://api.deepwiki.yourdomain.com
    ports:
      - "3000:3000"
    depends_on:
      - deepwiki-api
    restart: unless-stopped

Kubernetes Deployment

apiVersion: v1
kind: Secret
metadata:
  name: deepwiki-auth
type: Opaque
stringData:
  auth-code: "prod-secure-auth-2024-XYZ789"
  google-api-key: "your_google_api_key"
  openai-api-key: "your_openai_api_key"

Monitoring and Alerting

Authentication Metrics

# Example monitoring setup
import logging
from collections import defaultdict
from time import time

# Metrics collection
auth_metrics = {
    'successful_auths': 0,
    'failed_auths': 0,
    'unique_ips': set(),
    'requests_per_hour': defaultdict(int)
}

def track_auth_attempt(ip_address, success):
    current_hour = int(time()) // 3600
    
    if success:
        auth_metrics['successful_auths'] += 1
    else:
        auth_metrics['failed_auths'] += 1
        
    auth_metrics['unique_ips'].add(ip_address)
    auth_metrics['requests_per_hour'][current_hour] += 1
    
    # Alert on suspicious activity
    if auth_metrics['failed_auths'] > 50:
        send_security_alert("High number of failed authentications")

Grafana Dashboard

{
  "dashboard": {
    "title": "DeepWiki Authorization",
    "panels": [
      {
        "title": "Authentication Success Rate",
        "type": "stat",
        "targets": [
          {
            "expr": "rate(deepwiki_auth_success_total[5m]) / rate(deepwiki_auth_attempts_total[5m]) * 100"
          }
        ]
      },
      {
        "title": "Failed Authentication Attempts",
        "type": "graph",
        "targets": [
          {
            "expr": "rate(deepwiki_auth_failures_total[1m])"
          }
        ]
      },
      {
        "title": "Unique IPs per Hour",
        "type": "bargraph",
        "targets": [
          {
            "expr": "increase(deepwiki_unique_ips_total[1h])"
          }
        ]
      }
    ]
  }
}

Log Analysis

# Analyze authentication logs
grep "Authorization" api/logs/application.log | tail -100

# Failed authentication attempts
grep "Authorization.*invalid" api/logs/application.log | wc -l

# Unique IP addresses attempting authentication
grep "Authorization" api/logs/application.log | \
  grep -oE '([0-9]{1,3}\.){3}[0-9]{1,3}' | \
  sort | uniq -c | sort -nr

# Successful authentications per hour
grep "Authorization.*success" api/logs/application.log | \
  awk '{print $1" "$2}' | cut -c1-13 | uniq -c

Best Practices

Development Workflow

Local Development

# Use simple auth codes for development
DEEPWIKI_AUTH_MODE=true
DEEPWIKI_AUTH_CODE=dev-123

# Enable detailed logging
LOG_LEVEL=DEBUG

Staging Environment

# Use production-like codes
DEEPWIKI_AUTH_MODE=true  
DEEPWIKI_AUTH_CODE=staging-secure-2024

# Test authorization workflows thoroughly

Production Deployment

# Strong authorization codes
DEEPWIKI_AUTH_MODE=true
DEEPWIKI_AUTH_CODE=complex-random-production-code

# Minimal logging
LOG_LEVEL=WARNING
LOG_SENSITIVE_DATA=false

Team Management

Code Distribution

Secure methods for sharing authorization codes:

Encrypted communication:
- Use encrypted messaging (Signal, encrypted email)
- Password managers with secure sharing
- Company secrets management systems

Documentation:

# Team Wiki Access

Authorization code: [Available in team password manager]
Location: Team Vault > DeepWiki > Production Access
Updated: 2024-01-15
Next rotation: 2024-02-15

Onboarding process:
- Include authorization code in new team member setup
- Document where to find current codes
- Explain rotation schedule and notifications

Access Levels

Multiple authorization codes for different access levels:

# Different codes for different environments
DEEPWIKI_AUTH_CODE_READONLY=readonly-access-2024
DEEPWIKI_AUTH_CODE_FULL=full-access-2024-secure
DEEPWIKI_AUTH_CODE_ADMIN=admin-access-ultra-secure-2024

Implementation:

# Multiple authorization codes
VALID_AUTH_CODES = {
    'readonly': os.getenv('DEEPWIKI_AUTH_CODE_READONLY'),
    'full': os.getenv('DEEPWIKI_AUTH_CODE_FULL'),
    'admin': os.getenv('DEEPWIKI_AUTH_CODE_ADMIN')
}

def validate_auth_code(code, required_level='readonly'):
    allowed_levels = {
        'readonly': ['readonly', 'full', 'admin'],
        'full': ['full', 'admin'],
        'admin': ['admin']
    }
    
    for level in allowed_levels[required_level]:
        if VALID_AUTH_CODES[level] == code:
            return True, level
    
    return False, None

Security Maintenance

Regular Code Rotation

#!/bin/bash
# auth-rotation.sh - Automated code rotation

# Generate new auth code
NEW_CODE="wiki-$(date +%Y%m%d)-$(openssl rand -hex 6)"

# Update environment
echo "New authorization code: $NEW_CODE"
echo "Update DEEPWIKI_AUTH_CODE in production environment"

# Log rotation
echo "$(date): Code rotated to $NEW_CODE" >> auth-rotation.log

Access Auditing

# Audit script
def audit_auth_access():
    with open('api/logs/application.log', 'r') as f:
        auth_events = [
            line for line in f 
            if 'Authorization' in line
        ]
    
    print(f"Total auth events: {len(auth_events)}")
    print(f"Successful: {len([e for e in auth_events if 'success' in e])}")
    print(f"Failed: {len([e for e in auth_events if 'invalid' in e])}")

Security Monitoring

# Monitor for security issues
tail -f api/logs/application.log | grep -i "auth\|security\|unauthorized"

# Set up alerts for suspicious activity
grep -c "Authorization.*invalid" api/logs/application.log | \
  awk '{if ($1 > 10) print "ALERT: High auth failure rate"}'

Next Steps

Production Setup

Complete production deployment with authorization mode

API Authentication

Learn about complete API authentication and security

Private Repositories

Configure access to private repositories with tokens

Security Best Practices

Implement comprehensive security measures

Get Started

Configuration

Advanced

Support

​What is Authorization Mode?

Frontend Protection

API Security

Resource Control

Access Logging

​When to Use Authorization Mode

​Recommended Scenarios

​When NOT to Use Authorization Mode

​Configuration

​Environment Variables

​Basic Configuration

​Advanced Configuration

​Frontend Usage

​Authorization Code Input

​User Experience Flow

​Frontend Implementation

​API Usage

​Including Authorization Codes

​Authorization Validation Endpoint

​Security Considerations

​Authorization Code Security

​Attack Prevention

​Troubleshooting

​Common Issues

​Debugging Steps

​Production Deployment

​Docker Configuration

​Kubernetes Deployment

​Monitoring and Alerting

​Best Practices

​Development Workflow

​Team Management

​Security Maintenance

​Next Steps

Production Setup

API Authentication

Private Repositories

Security Best Practices

What is Authorization Mode?

When to Use Authorization Mode

Recommended Scenarios

When NOT to Use Authorization Mode

Configuration

Environment Variables

Basic Configuration

Advanced Configuration

Frontend Usage

Authorization Code Input

User Experience Flow

Frontend Implementation

API Usage

Including Authorization Codes

Authorization Validation Endpoint

Security Considerations

Authorization Code Security

Attack Prevention

Troubleshooting

Common Issues

Debugging Steps

Production Deployment

Docker Configuration

Kubernetes Deployment

Monitoring and Alerting

Best Practices

Development Workflow

Team Management

Security Maintenance

Next Steps