# How to Add Authentication to GPT Academic: A Complete Guide

> Learn how to add authentication to GPT Academic. Secure your application by configuring username-password authentication via config.py or environment variables. Follow our complete guide.

- Repository: [binary-husky/gpt_academic](https://github.com/binary-husky/gpt_academic)
- Tags: how-to-guide
- Published: 2026-03-02

---

**GPT Academic includes a built-in username-password authentication system that you can activate by populating the `AUTHENTICATION` list in [`config.py`](https://github.com/binary-husky/gpt_academic/blob/main/config.py) or setting the `GPT_ACADEMIC_AUTHENTICATION` environment variable.**

GPT Academic is an open-source LLM interaction framework that provides a Gradio-based web interface for academic paper processing and translation. By default, the application runs without authentication, but the codebase includes a complete access control layer that protects the UI and sensitive user files. This guide explains how to enable and configure authentication using the native mechanisms found in the source code.

## Understanding GPT Academic's Built-In Authentication System

The authentication architecture relies on four core components that work together to secure the FastAPI/Gradio application:

| Component | Location | Function |
|-----------|----------|----------|
| **`AUTHENTICATION`** | [`config.py`](https://github.com/binary-husky/gpt_academic/blob/main/config.py) (lines 199-203) | Stores a list of `(username, password)` tuples. When non-empty, it triggers the login screen. |
| **`_authorize_user`** | [`shared_utils/fastapi_server.py`](https://github.com/binary-husky/gpt_academic/blob/main/shared_utils/fastapi_server.py) (lines 72-90) | Validates request cookies (`access-token` / `access-token-unsecure`) against the token store and verifies file access permissions. |
| **`start_app`** | [`shared_utils/fastapi_server.py`](https://github.com/binary-husky/gpt_academic/blob/main/shared_utils/fastapi_server.py) (lines 120-147) | Wires authentication into the FastAPI stack, replaces file routes with protected wrappers, and sets `app_block.auth` to enable the Gradio login dialog. |
| **[`main.py`](https://github.com/binary-husky/gpt_academic/blob/main/main.py)** | [`main.py`](https://github.com/binary-husky/gpt_academic/blob/main/main.py) (lines 50-55) | Retrieves the `AUTHENTICATION` value from the configuration loader and passes it to `start_app`. |

When `AUTHENTICATION` contains valid credentials, `start_app` automatically sets `app_block.auth_message = '请登录'` (Please log in) and configures Gradio to render the authentication modal before granting access to the interface.

## How to Enable Authentication in GPT Academic

You can activate authentication using either the configuration file or environment variables. The configuration loader in [`shared_utils/config_loader.py`](https://github.com/binary-husky/gpt_academic/blob/main/shared_utils/config_loader.py) prioritizes environment variables over [`config.py`](https://github.com/binary-husky/gpt_academic/blob/main/config.py) values, making environment variables ideal for production deployments.

### Method 1: Configure via config.py

Edit the `AUTHENTICATION` list in [`config.py`](https://github.com/binary-husky/gpt_academic/blob/main/config.py) to define allowed users:

```python

# config.py – around line 199

AUTHENTICATION = [
    ("admin", "StrongP@ssw0rd123"),
    ("researcher1", "SecurePass456"),
    ("student_a", "UserPass789"),
]

```

Save the file and restart the application. The Gradio interface will now display a login screen before loading the main UI.

### Method 2: Use Environment Variables (Recommended)

For Docker deployments or shared servers, set the `GPT_ACADEMIC_AUTHENTICATION` environment variable to avoid committing credentials to version control:

```bash
export GPT_ACADEMIC_AUTHENTICATION='[("admin","StrongP@ssw0rd123"),("user2","Pass456")]'
python main.py

```

Or using Docker:

```bash
docker run -e GPT_ACADEMIC_AUTHENTICATION='[("admin","StrongP@ssw0rd123")]' -p 7860:7860 gpt_academic

```

The [`config_loader.py`](https://github.com/binary-husky/gpt_academic/blob/main/config_loader.py) module parses this string into the same list structure used by [`config.py`](https://github.com/binary-husky/gpt_academic/blob/main/config.py), ensuring consistent behavior across deployment methods.

## How the Authentication Flow Protects Your Data

Once enabled, the authentication system secures two critical areas: the Gradio UI and file system access.

### UI Protection

When `start_app` detects a non-empty `AUTHENTICATION` list, it assigns the credentials to `app_block.auth`. Gradio then intercepts all incoming requests and presents a login modal. Successful authentication stores two cookies in the browser:
- `access-token`: The secure session token
- `access-token-unsecure`: A fallback identifier

### File Access Control

The `_authorize_user` function in [`fastapi_server.py`](https://github.com/binary-husky/gpt_academic/blob/main/fastapi_server.py) (lines 72-90) validates every request to `/file/` endpoints. It performs two checks:
1. Verifies the request contains valid cookies from the Gradio token store
2. Ensures the requested file path resides within the user's private upload directory (`PATH_PRIVATE_UPLOAD`) or the logging directory (`PATH_LOGGING`)

If either check fails, the function returns `"越权访问!"` (Unauthorized access) and blocks the request. This prevents users from accessing other users' uploaded files or sensitive system logs.

## Programmatic Access and API Authentication

For automated scripts or API clients, you must handle the authentication flow programmatically. The following Python example demonstrates logging in and accessing protected files:

```python
import requests

BASE_URL = "http://localhost:7860"

# Step 1: Retrieve the login page to establish session context

session = requests.Session()
login_page = session.get(f"{BASE_URL}/").text

# Step 2: Submit credentials to the Gradio login endpoint

# Note: The exact endpoint may vary based on Gradio version; 

# typically it posts to the root or a /login path

resp = session.post(
    f"{BASE_URL}/login",
    data={"username": "admin", "password": "StrongP@ssw0rd123"},
    allow_redirects=True
)

# Step 3: Access protected resources using the session cookies

# The session object automatically handles the access-token cookie

file_response = session.get(f"{BASE_URL}/file/private_upload/admin/report.pdf")
print(file_response.status_code)  # Should be 200 if authorized

```

To log out and clear the session:

```python

# Step 4: Logout to invalidate the session

session.get(f"{BASE_URL}/academic_logout")

```

## Summary

- **GPT Academic includes built-in authentication** controlled by the `AUTHENTICATION` variable in [`config.py`](https://github.com/binary-husky/gpt_academic/blob/main/config.py) or the `GPT_ACADEMIC_AUTHENTICATION` environment variable.
- **Enable security** by populating the authentication list with `(username, password)` tuples and restarting the server; Gradio automatically renders a login modal.
- **File protection** is enforced by `_authorize_user` in [`fastapi_server.py`](https://github.com/binary-husky/gpt_academic/blob/main/fastapi_server.py), which validates cookies and restricts access to private upload and logging directories.
- **Environment variables** are the recommended approach for production deployments to avoid committing credentials to version control.

## Frequently Asked Questions

### Where is the AUTHENTICATION variable defined in GPT Academic?

The `AUTHENTICATION` variable is defined in [`config.py`](https://github.com/binary-husky/gpt_academic/blob/main/config.py) at lines 199-203. It defaults to an empty list `[]`, which means no authentication is required. The configuration loader in [`shared_utils/config_loader.py`](https://github.com/binary-husky/gpt_academic/blob/main/shared_utils/config_loader.py) also checks for the environment variable `GPT_ACADEMIC_AUTHENTICATION`, which takes precedence over the value in [`config.py`](https://github.com/binary-husky/gpt_academic/blob/main/config.py) if set.

### Can I use external SSO providers like OAuth or LDAP with GPT Academic?

The current implementation in [`shared_utils/fastapi_server.py`](https://github.com/binary-husky/gpt_academic/blob/main/shared_utils/fastapi_server.py) uses a simple cookie-based token system managed by Gradio. To use external SSO providers, you would need to modify the `_authorize_user` function (lines 72-90) to validate JWT tokens or session tickets from your identity provider instead of checking Gradio's token store. The rest of the file route protection mechanism would remain the same.

### How do I disable authentication in GPT Academic?

To disable authentication, set `AUTHENTICATION = []` in [`config.py`](https://github.com/binary-husky/gpt_academic/blob/main/config.py) or unset the environment variable `GPT_ACADEMIC_AUTHENTICATION`. When the list is empty, the `start_app` function in [`fastapi_server.py`](https://github.com/binary-husky/gpt_academic/blob/main/fastapi_server.py) (lines 120-147) skips the authentication setup, leaving file routes unprotected and allowing direct access to the Gradio interface without a login screen.

### What files and routes are protected when authentication is enabled?

When authentication is active, the `_authorize_user` function protects all routes under `/file/`. Specifically, users can only access files within their private upload directory (`PATH_PRIVATE_UPLOAD`) and the logging directory (`PATH_LOGGING`). The system checks the `access-token` cookie against Gradio's token store and verifies the requested file path belongs to the authenticated user, returning "越权访问!" (unauthorized access) for any invalid requests.