How DeepWiki Authorization Mode Secures Wiki Generation with Environment-Based Secret Codes

DeepWiki's authorization mode protects destructive operations by requiring a secret code configured via environment variables, validating client requests against stored credentials before allowing privileged actions like cache deletion.

DeepWiki, an open-source wiki generation tool from the AsyncFuncAI/deepwiki-open repository, implements an optional DeepWiki authorization mode that adds a security layer to sensitive operations. This mechanism leverages environment variables to store authentication credentials, ensuring that only clients possessing the correct secret code can execute destructive commands while keeping generation and export endpoints publicly accessible.

How DeepWiki Authorization Mode Works

The authorization system operates through a five-step flow controlled by environment configuration and enforced at specific FastAPI endpoints. When enabled, the mode gates privileged actions while leaving read-only and generation endpoints open.

Enabling Authorization Mode via Environment Variables

Configuration begins in api/config.py, where the application reads two critical environment variables at startup. Lines 47-48 normalize DEEPWIKI_AUTH_MODE to a Boolean flag WIKI_AUTH_MODE, accepting truthy values like true, 1, or t. Line 49 stores DEEPWIKI_AUTH_CODE as WIKI_AUTH_CODE, which serves as the master secret for validation.

Checking Authentication Status

Clients determine whether authentication is required by querying GET /auth/status. Implemented in api/api.py at lines 153-158, this endpoint returns a JSON object {"auth_required": <bool>} based on the WIKI_AUTH_MODE configuration. UIs use this response to conditionally display password prompts.

Validating the Secret Code

When a client submits a potential secret, the application verifies it through POST /auth/validate. Located at lines 160-166 in api/api.py, this endpoint accepts a JSON payload {"code": "<user-input>"} and compares the value against WIKI_AUTH_CODE. It returns {"success": true} only when the strings match exactly, enabling pre-flight checks before destructive operations.

Protecting Destructive Operations

The actual enforcement occurs at privileged endpoints such as DELETE /api/wiki_cache. As implemented in api/api.py at lines 520-525, this route first inspects WIKI_AUTH_MODE. When enabled, it requires the query parameter authorization_code to equal WIKI_AUTH_CODE; otherwise, it returns HTTP 401. This ensures that cache deletion—a destructive, irreversible action—requires explicit authorization.

Implementation Examples

The following examples demonstrate how to interact with DeepWiki's authorization endpoints using Python and the requests library.

Checking if Authentication is Required

import requests

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

if status["auth_required"]:
    print("Authentication required: Please provide the secret code.")
else:
    print("Public access: No authentication needed.")

Validating a User-Provided Code

import requests

payload = {"code": "my-super-secret-code"}
response = requests.post(
    "http://localhost:8000/auth/validate", 
    json=payload
)

if response.json()["success"]:
    print("Code validated successfully.")
else:
    print("Invalid authorization code.")

Executing Protected Operations

import requests

params = {
    "owner": "AsyncFuncAI",
    "repo": "deepwiki-open",
    "repo_type": "github",
    "language": "en",
    "authorization_code": "my-super-secret-code"
}

response = requests.delete(
    "http://localhost:8000/api/wiki_cache", 
    params=params
)

print(f"Status: {response.status_code}")
print(response.json())

Key Source Files

The authorization logic is concentrated in two core modules within the AsyncFuncAI/deepwiki-open repository:

• api/config.py: Loads and normalizes environment variables DEEPWIKI_AUTH_MODE and DEEPWIKI_AUTH_CODE into application constants WIKI_AUTH_MODE and WIKI_AUTH_CODE at startup (lines 47-49).

• api/api.py: Implements the FastAPI endpoints for status checking (/auth/status at lines 153-158), code validation (/auth/validate at lines 160-166), and protected route enforcement (DELETE /api/wiki_cache at lines 520-525).

Summary

• DeepWiki authorization mode is opt-in via the DEEPWIKI_AUTH_MODE environment variable, making it backward compatible with open deployments.
• The secret code is configured externally through DEEPWIKI_AUTH_CODE, ensuring credentials never appear in source control.
• Clients can discover authentication requirements dynamically via the /auth/status endpoint, enabling adaptive user interfaces.
• The system validates secrets through a dedicated /auth/validate endpoint before clients attempt protected operations.
• Destructive actions like cache deletion are gated by requiring the authorization_code query parameter to match the configured secret, returning HTTP 401 on mismatch.

Frequently Asked Questions

What happens if I enable authorization mode but forget to set the secret code?

If DEEPWIKI_AUTH_MODE is enabled but DEEPWIKI_AUTH_CODE is empty or unset, the application will still require authentication for protected endpoints. However, validation will fail for any non-empty code provided by clients, effectively blocking all privileged operations until a valid secret is configured in the environment.

Can I use DeepWiki authorization mode with reverse proxy authentication?

Yes. Since DeepWiki reads the secret code exclusively from environment variables, you can deploy it behind a reverse proxy (such as Nginx or Traefik) that handles OAuth, JWT, or mTLS authentication. The proxy would simply pass the validated secret code to DeepWiki via the authorization_code parameter when calling protected endpoints like DELETE /api/wiki_cache.

Which endpoints are protected by the authorization mode?

Currently, only destructive or administrative endpoints enforce the authorization check. Specifically, DELETE /api/wiki_cache requires the authorization_code parameter when WIKI_AUTH_MODE is enabled. All generation, export, and read-only endpoints—including wiki creation and retrieval—remain publicly accessible regardless of the authorization mode setting.

How do I rotate the secret code without restarting the application?

The current implementation loads DEEPWIKI_AUTH_CODE into WIKI_AUTH_CODE at startup time in api/config.py. To rotate the secret, you must update the environment variable and restart the DeepWiki service. There is no hot-reload mechanism for the authorization code in the current codebase, so a service restart is required to apply new credentials.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}