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

> Learn how DeepWiki authorization mode secures wiki generation using environment-based secret codes. Protect your wiki with secure credential validation for privileged actions.

- Repository: [ASYNCFUNC/deepwiki-open](https://github.com/asyncfuncai/deepwiki-open)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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](https://github.com/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`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/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`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/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`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/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`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/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

```python
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

```python
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

```python
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`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/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`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/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`](https://github.com/AsyncFuncAI/deepwiki-open/blob/main/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.