API Authentication - DeepWiki-Open

The DeepWiki-Open API supports multiple authentication methods to secure your documentation generation service. This guide covers all authentication options, security configurations, and best practices.

Authentication Overview

DeepWiki-Open uses a multi-layered authentication approach:

Environment-Based Auth

API provider keys configured via environment variables

Authorization Mode

Optional secret code protection for wiki generation

Repository Tokens

Personal access tokens for private repository access

Request Validation

Input validation and rate limiting protection

Environment-Based Authentication

API Provider Authentication

The API automatically validates configured AI provider credentials:

Google Gemini
OpenAI
Azure OpenAI

string

Uses GOOGLE_API_KEY from environment automatically

Validation endpoint:

curl -X GET "http://localhost:8001/auth/validate/google"

Response:

{
  "provider": "google",
  "status": "valid",
  "models_available": [
    "gemini-2.0-flash",
    "gemini-1.5-flash",
    "gemini-1.0-pro"
  ],
  "quota": {
    "requests_per_minute": 15,
    "tokens_per_minute": 32000,
    "usage_today": "12%"
  }
}

string

Uses OPENAI_API_KEY from environment automatically

Validation endpoint:

curl -X GET "http://localhost:8001/auth/validate/openai"

Response:

{
  "provider": "openai",
  "status": "valid", 
  "models_available": [
    "gpt-4o",
    "gpt-4.1", 
    "o1",
    "o4-mini"
  ],
  "quota": {
    "tier": "tier-2",
    "requests_per_minute": 500,
    "tokens_per_minute": 30000,
    "current_usage": "8%"
  }
}

string

Uses Azure credentials from environment

Required environment variables:

AZURE_OPENAI_API_KEY=your_api_key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_VERSION=2024-02-15-preview

Validation:

curl -X GET "http://localhost:8001/auth/validate/azure"

Authentication Status

Check overall authentication status:

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

import requests

response = requests.get("http://localhost:8001/auth/status")
auth_status = response.json()

const response = await fetch('http://localhost:8001/auth/status');
const authStatus = await response.json();

{
  "authentication": {
    "overall_status": "healthy",
    "providers": {
      "google": {
        "configured": true,
        "valid": true,
        "models_count": 3
      },
      "openai": {
        "configured": true,
        "valid": true,
        "models_count": 4
      },
      "openrouter": {
        "configured": false,
        "valid": null,
        "models_count": 0
      },
      "azure": {
        "configured": true,
        "valid": true,
        "models_count": 2
      },
      "ollama": {
        "configured": true,
        "valid": true,
        "models_count": 3,
        "local": true
      }
    },
    "recommended_provider": "google",
    "fallback_providers": ["openai", "azure"]
  },
  "authorization": {
    "mode": "disabled",
    "required": false
  }
}

Authorization Mode

Optional access control requiring a secret code for wiki generation.

Enabling Authorization Mode

Configure Environment

Set authorization environment variables:

DEEPWIKI_AUTH_MODE=true
DEEPWIKI_AUTH_CODE=your-secret-code-here

Choose a strong, unique authorization code. This provides basic access control.

Restart API Server

Authorization mode requires a server restart:

# Stop current server
# Restart with new configuration
python -m api.main

Server logs should show: “Authorization mode: ENABLED”

Verify Configuration

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

Should show:

{
  "authorization": {
    "mode": "enabled", 
    "required": true
  }
}

Using Authorization Mode

When authorization is enabled, all wiki generation requests must include the auth code:

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

import requests

response = requests.post("http://localhost:8001/wiki/generate", json={
    "repo_url": "https://github.com/microsoft/vscode",
    "model_provider": "google",
    "auth_code": "your-secret-code-here"
})

const response = await fetch('http://localhost:8001/wiki/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    repo_url: 'https://github.com/microsoft/vscode',
    model_provider: 'google',
    auth_code: 'your-secret-code-here'
  })
});

Authorization Validation

Test authorization codes before use:

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

{
  "valid": true,
  "message": "Authorization code accepted"
}

{
  "valid": false,
  "message": "Invalid authorization code",
  "error": "AUTHORIZATION_FAILED"
}

Repository Access Tokens

For accessing private repositories, provide personal access tokens.

Supported Platforms

GitHub
GitLab
BitBucket

Token creation:

Go to GitHub Settings → Developer settings → Personal access tokens
Generate new token (classic or fine-grained)
Select scopes: repo (full repository access)

Token format: ghp_xxxxxxxxxxxxxxxxxxxx (classic) or github_pat_xxxx (fine-grained)Usage in requests:

{
  "repo_url": "https://github.com/company/private-repo",
  "access_token": "ghp_xxxxxxxxxxxxxxxxxxxx",
  "model_provider": "google"
}

Token creation:

Go to GitLab User Settings → Access Tokens
Create personal access token
Select scopes: read_repository

Token format: glpat-xxxxxxxxxxxxxxxxxxxxUsage in requests:

{
  "repo_url": "https://gitlab.com/company/private-repo",
  "access_token": "glpat-xxxxxxxxxxxxxxxxxxxx",
  "model_provider": "google"
}

Token creation:

Go to BitBucket Account Settings → App passwords
Create app password
Select permissions: Repositories: Read

Token format: App-specific passwordUsage in requests:

{
  "repo_url": "https://bitbucket.org/company/private-repo", 
  "access_token": "your-app-password",
  "model_provider": "google"
}

Token Validation

Validate repository access tokens:

curl -X POST "http://localhost:8001/auth/validate-token" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "github",
    "token": "ghp_xxxxxxxxxxxxxxxxxxxx"
  }'

{
  "valid": true,
  "platform": "github",
  "scopes": ["repo", "user"],
  "user": "your-username",
  "expires_at": "2024-12-31T23:59:59Z"
}

{
  "valid": false,
  "platform": "github", 
  "error": "BAD_CREDENTIALS",
  "message": "Token is invalid or expired"
}

Security Best Practices

Environment Security

API Key Management

Secure storage:

# Use environment files with restricted permissions
chmod 600 .env

# Never commit API keys to version control
echo ".env" >> .gitignore

# Use different keys for development and production
# .env.development vs .env.production

Key rotation:

# Regular key rotation schedule
# 1. Generate new API keys
# 2. Test with new keys
# 3. Update production environment
# 4. Revoke old keys
# 5. Monitor for any issues

Monitoring:

{
  "api_key_monitoring": {
    "check_quota_daily": true,
    "alert_on_high_usage": true,
    "track_failed_requests": true,
    "log_security_events": true
  }
}

Network Security

HTTPS configuration:

# Nginx configuration for HTTPS
server {
    listen 443 ssl;
    server_name deepwiki.yourdomain.com;
    
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    
    location / {
        proxy_pass http://localhost:8001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Firewall rules:

# Only allow necessary ports
sudo ufw allow 22    # SSH
sudo ufw allow 80    # HTTP (redirect to HTTPS)
sudo ufw allow 443   # HTTPS
sudo ufw deny 8001   # Block direct API access
sudo ufw enable

Request Validation

Input sanitization:

# Example validation middleware
def validate_repo_url(url: str) -> bool:
    allowed_domains = [
        'github.com',
        'gitlab.com', 
        'bitbucket.org'
    ]
    
    parsed = urlparse(url)
    return (
        parsed.scheme in ['https'] and
        parsed.netloc in allowed_domains and
        len(parsed.path.split('/')) >= 3
    )

Rate limiting:

{
  "rate_limits": {
    "requests_per_minute": 10,
    "requests_per_hour": 100,
    "requests_per_day": 1000,
    "burst_allowance": 5
  }
}

Production Security

Authentication Hardening

# Production security settings
DEEPWIKI_AUTH_MODE=true
DEEPWIKI_AUTH_CODE=complex-random-string-here

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

Access Control

# Restrict API access to authorized IPs
# Using firewall or reverse proxy
iptables -A INPUT -p tcp --dport 8001 -s 192.168.1.0/24 -j ACCEPT
iptables -A INPUT -p tcp --dport 8001 -j DROP

Monitoring & Alerting

{
  "security_monitoring": {
    "failed_auth_attempts": {
      "threshold": 10,
      "window": "1h", 
      "action": "alert"
    },
    "unusual_usage_patterns": {
      "detect_anomalies": true,
      "baseline_days": 7
    },
    "api_abuse_detection": {
      "large_repository_attempts": true,
      "rapid_fire_requests": true
    }
  }
}

Error Handling

Authentication Errors

{
  "error": {
    "code": "MISSING_API_KEYS",
    "message": "No valid AI provider API keys configured",
    "details": {
      "configured_providers": [],
      "required_providers": ["google", "openai", "openrouter"],
      "suggestion": "Configure at least one AI provider API key"
    }
  }
}

{
  "error": {
    "code": "AUTHORIZATION_REQUIRED",
    "message": "Authorization code required but not provided",
    "details": {
      "auth_mode": "enabled",
      "provided_code": null,
      "suggestion": "Include 'auth_code' in request body"
    }
  }
}

{
  "error": {
    "code": "REPOSITORY_ACCESS_DENIED",
    "message": "Cannot access private repository",
    "details": {
      "repo_url": "https://github.com/company/private-repo",
      "platform": "github",
      "suggestion": "Provide valid access token with repository permissions"
    }
  }
}

Token Validation Errors

Expired Tokens

{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Repository access token has expired",
    "details": {
      "platform": "github",
      "expired_at": "2024-01-15T10:30:00Z",
      "suggestion": "Generate new personal access token"
    }
  }
}

Resolution:

Generate new personal access token
Update request with new token
Consider using longer-lived tokens for automation

Insufficient Permissions

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS", 
    "message": "Token lacks required repository permissions",
    "details": {
      "platform": "github",
      "required_scopes": ["repo"],
      "current_scopes": ["user"],
      "suggestion": "Create token with 'repo' scope for private repositories"
    }
  }
}

Resolution:

Create new token with correct scopes
For GitHub: include repo scope for private repositories
For GitLab: include read_repository scope

Integration Examples

Middleware Authentication

from functools import wraps
from flask import request, jsonify

def require_auth(f):
    @wraps(f)
    def decorated_function(*args, **kwargs):
        auth_code = request.json.get('auth_code')
        
        if not validate_auth_code(auth_code):
            return jsonify({
                'error': 'Invalid or missing authorization code'
            }), 401
            
        return f(*args, **kwargs)
    return decorated_function

@app.route('/wiki/generate', methods=['POST'])
@require_auth
def generate_wiki():
    # Wiki generation logic
    pass

const authenticateRequest = (req, res, next) => {
  const { auth_code } = req.body;
  
  if (!validateAuthCode(auth_code)) {
    return res.status(401).json({
      error: 'Invalid or missing authorization code'
    });
  }
  
  next();
};

app.post('/wiki/generate', authenticateRequest, (req, res) => {
  // Wiki generation logic
});

Client-Side Authentication

import { useState, useEffect } from 'react';

export function useDeepWikiAuth() {
  const [authStatus, setAuthStatus] = useState(null);
  
  useEffect(() => {
    checkAuthStatus();
  }, []);
  
  const checkAuthStatus = async () => {
    try {
      const response = await fetch('/api/auth/status');
      const status = await response.json();
      setAuthStatus(status);
    } catch (error) {
      console.error('Auth check failed:', error);
    }
  };
  
  const validateAuthCode = async (code) => {
    try {
      const response = await fetch('/api/auth/validate', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ auth_code: code })
      });
      return response.ok;
    } catch (error) {
      return false;
    }
  };
  
  return { authStatus, validateAuthCode, checkAuthStatus };
}

Next Steps

Wiki Endpoints

Learn about wiki generation and management endpoints

Security Guide

Implement comprehensive security measures

Production Setup

Deploy with proper authentication in production

Monitoring

Set up authentication monitoring and alerts

​Authentication Overview

Environment-Based Auth

Authorization Mode

Repository Tokens

Request Validation

​Environment-Based Authentication

​API Provider Authentication

​Authentication Status

​Authorization Mode

​Enabling Authorization Mode

​Using Authorization Mode

​Authorization Validation

​Repository Access Tokens

​Supported Platforms

​Token Validation

​Security Best Practices

​Environment Security

​Production Security

​Error Handling

​Authentication Errors

​Token Validation Errors

​Integration Examples

​Middleware Authentication

​Client-Side Authentication

​Next Steps

Wiki Endpoints

Security Guide

Production Setup

Monitoring

Authentication Overview

Environment-Based Authentication

API Provider Authentication

Authentication Status

Authorization Mode

Enabling Authorization Mode

Using Authorization Mode

Authorization Validation

Repository Access Tokens

Supported Platforms

Token Validation

Security Best Practices

Environment Security

Production Security

Error Handling

Authentication Errors

Token Validation Errors

Integration Examples

Middleware Authentication

Client-Side Authentication

Next Steps