# How Chat2DB Handles Authentication and Authorization: Token-Based Security Explained

> Discover how Chat2DB secures its APIs with a simple token system. Learn about its UUID tokens, custom HTTP headers, and environment variables for robust authentication and authorization, bypassing complex frameworks like Spring...

- Repository: [OtterMind/Chat2DB](https://github.com/OtterMind/Chat2DB)
- Tags: internals
- Published: 2026-07-27

---

**Chat2DB secures its desktop and CLI APIs using a lightweight UUID token system that validates requests via a custom HTTP header or environment variable rather than a full Spring Security framework.**

Chat2DB is an open-source database management tool that implements a simple but effective token-based security model across its community edition server. The Chat2DB authentication and authorization mechanism generates a unique token at startup and enforces it through client-specific interceptors and filters. This design keeps the security surface small while protecting desktop and CLI entry points.

## Token Generation and Storage

When the application starts, the system checks for an existing MCP token and creates one if it is absent. The `SystemSettingsUtil.getOrCreateMcpAuthToken()` method generates a UUID without dashes and persists it under the key `MCP_AUTH_TOKEN` in system settings.

```java
// chat2db-community-server/chat2db-community-tools/src/main/java/ai/chat2db/community/tools/util/SystemSettingsUtil.java
String authToken = SystemSettingsUtil.getOrCreateMcpAuthToken();

```

The same utility class retrieves the stored token later for request validation.

## Desktop Client Authentication via X-Chat2DB-MCP-Token

All HTTP requests originating from the **desktop client** must carry the custom header `X-Chat2DB-MCP-Token`. The header constant is defined in [`McpSecurityConstants.java`](https://github.com/OtterMind/Chat2DB/blob/main/McpSecurityConstants.java) at the path [`chat2db-community-server/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/config/mcp/security/McpSecurityConstants.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/config/mcp/security/McpSecurityConstants.java).

### McpAuthInterceptor and Header Validation

The `McpAuthInterceptor` intercepts incoming desktop requests, extracts the `X-Chat2DB-MCP-Token` header, and compares it against the value stored by `SystemSettingsUtil`. If the header is missing or the value does not match, the request is rejected with the error code `common.mcpUnauthorized`.

```java
// chat2db-community-server/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/config/mcp/interceptor/McpAuthInterceptor.java
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
    String headerToken = request.getHeader("X-Chat2DB-MCP-Token");
    String storedToken = SystemSettingsUtil.getOrCreateMcpAuthToken();
    
    if (headerToken == null || !headerToken.equals(storedToken)) {
        throw new BusinessException("common.mcpUnauthorized");
    }
    return true;
}

```

## CLI Runtime Authentication via Environment Variables

The CLI client authenticates through a **bearer token** supplied via the environment variable `chat2db.cli.runtime.token` or the Java system property `chat2db.cli.runtime.token`. This token is validated by `CliRuntimeHttpFilter` on incoming API calls meant for the CLI.

### CliRuntimeHttpFilter and Bearer Token Checks

`CliRuntimeHttpFilter` checks for the presence and validity of the CLI runtime token. Missing tokens trigger the error code `cli_runtime_token_missing`, while invalid tokens return `cli_runtime_unauthorized`.

```java
// chat2db-community-server/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/config/cli/security/CliRuntimeHttpFilter.java
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
    String token = System.getenv("chat2db.cli.runtime.token");
    if (token == null) {
        token = System.getProperty("chat2db.cli.runtime.token");
    }
    
    if (token == null) {
        writeError(response, "cli_runtime_token_missing");
        return;
    }
    
    if (!isValid(token)) {
        writeError(response, "cli_runtime_unauthorized");
        return;
    }
    
    chain.doFilter(request, response);
}

```

## Implicit Authorization in Controllers

After successful token authentication, the request proceeds to the controller layer. Chat2DB does not implement fine-grained role-based access control in the source tree. Instead, **authorization is implicit**: most operations are permitted for any authenticated user because the tool is primarily developer-focused. The controller methods execute the requested operation directly once the token check passes.

This means there are no additional role checks after `McpAuthInterceptor` or `CliRuntimeHttpFilter` validate the request.

## Summary

- **Token generation**: `SystemSettingsUtil.getOrCreateMcpAuthToken()` creates and persists a UUID token under `MCP_AUTH_TOKEN` at startup.
- **Desktop authentication**: The `X-Chat2DB-MCP-Token` header is validated by `McpAuthInterceptor` against the stored UUID.
- **CLI authentication**: `CliRuntimeHttpFilter` checks the `chat2db.cli.runtime.token` environment variable or system property.
- **Error handling**: Invalid desktop requests return `common.mcpUnauthorized`; CLI failures return `cli_runtime_token_missing` or `cli_runtime_unauthorized`.
- **Authorization**: Once authenticated, users can execute operations without additional role checks.

## Frequently Asked Questions

### Does Chat2DB use Spring Security for authentication?

No. According to the Chat2DB source code, the community edition avoids a full Spring Security framework and instead relies on lightweight custom interceptors and filters. The `McpAuthInterceptor` and `CliRuntimeHttpFilter` handle validation independently using UUID tokens.

### What happens if the X-Chat2DB-MCP-Token header is missing?

The `McpAuthInterceptor` rejects the request and returns the error code `common.mcpUnauthorized`. This interceptor is defined in [`chat2db-community-server/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/config/mcp/interceptor/McpAuthInterceptor.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-web/src/main/java/ai/chat2db/community/web/api/config/mcp/interceptor/McpAuthInterceptor.java).

### How is the CLI token different from the desktop token?

The desktop client uses an MCP token passed in the `X-Chat2DB-MCP-Token` HTTP header, while the CLI client uses a runtime token configured through the `chat2db.cli.runtime.token` environment variable or system property. Each entry point has its own validation filter: `McpAuthInterceptor` for desktop and `CliRuntimeHttpFilter` for CLI.

### Is there role-based access control in Chat2DB?

No. The source code shows no fine-grained role checks. Chat2DB authentication and authorization are focused on simple token validation, and once a request is authenticated, controllers implicitly authorize the operation without further permission checks.