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"
  }'
{
  "success": true
}
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

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

1

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.
2

Restart Services

Authorization mode requires a full restart:
# Stop containers
docker-compose down

# Start with new configuration
docker-compose up -d

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

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

1

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
2

Code Entry

User enters the authorization code:
  • Code is masked (password field)
  • Real-time validation (optional)
  • Clear error messages for invalid codes
3

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

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

Debugging Steps

1

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'))
"
2

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"}'
3

Check Logs

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

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

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

Best Practices

Development Workflow

1

Local Development

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

# Enable detailed logging
LOG_LEVEL=DEBUG
2

Staging Environment

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

# Test authorization workflows thoroughly
3

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

Security Maintenance

1

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
2

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])}")
3

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