Authentication & OAuth
Relevant source files
The following files were used as context for generating this wiki page:
Authentication in QQcode is a multi-tiered system designed to support both traditional API key-based access and modern OAuth 2.0 flows. The system manages credentials for multiple AI providers including Anthropic (Claude), Mistral, OpenRouter, and Qwen. It facilitates secure storage, automatic token refreshment, and interactive user onboarding to ensure seamless communication with Large Language Model (LLM) backends.
The architecture separates authentication logic into environment-based keys, configuration-driven provider settings, and specialized OAuth handlers for providers that support subscription-based access or device-bound authorization.
Sources: vibe/core/config.py:165-240, vibe/setup/onboarding/screens/api_key.py:32-48, README.md
Authentication Architecture
The system utilizes a central configuration manager (VibeConfig) to orchestrate authentication. It prioritizes environment variables, followed by a .env file located in the ~/.qqcode/ directory, and finally provider-specific OAuth tokens stored in the config.toml.
Authentication Methods
| Method | Description | Primary Providers |
|---|---|---|
| API Key | Environment variables or .env file entries (e.g., MISTRAL_API_KEY). | Mistral, OpenRouter, Z.ai |
| OAuth 2.0 (PKCE) | Authorization code flow with Proof Key for Code Exchange. | Anthropic |
| Device Flow | Browser-based authorization for CLI/limited-input devices. | Qwen |
| No Auth | Local inference or proxy setups. | llama.cpp |
Sources: vibe/core/config.py:35-42, vibe/setup/onboarding/screens/api_key.py:32-48
Credentials Resolution Flow
The following diagram illustrates how the system resolves authentication credentials for a given request.
OAuth Implementation
OAuth support is primarily implemented for Anthropic and Qwen, allowing users to authenticate via their provider subscriptions.
PKCE and Authorization Code Flow (Anthropic)
For Anthropic, the system uses the PKCE extension to securely handle authorization codes in the CLI.
- Challenge Generation: The system generates a code verifier and a SHA-256 code challenge.
- Authorization: The user is redirected to the provider's authorize URL via a web browser.
- Token Exchange: The user pastes the resulting code back into the CLI, which exchanges it for an
AnthropicOAuthToken.
Sources: vibe/core/oauth/claude.py, vibe/cli/login.py:22-45, vibe/setup/onboarding/screens/api_key.py:269-281
Device Authorization Flow (Qwen)
For Qwen, the system implements a device flow where the CLI requests a device code and polls for the user's completion of the browser-based authorization.
Token Management
Tokens are represented as Pydantic models to ensure validation and provide expiry checking logic.
class OAuthToken(BaseModel):
access_token: str
refresh_token: str
expires_at: float
def is_expired(self) -> bool:
# Buffer of 60 seconds to prevent race conditions
return time.time() > self.expires_at - 60
Sources: vibe/core/oauth/token.py:10-25
Credential Persistence & Configuration
Credentials and authentication settings are persisted in the user's home directory (~/.qqcode/).
Configuration Files
.env: Stores raw API keys for various providers using theset_keyutility.config.toml: Contains structuredProviderConfigentries, including serializedoauth_tokenobjects.
Sources: vibe/core/config.py:20-30, vibe/setup/onboarding/screens/api_key.py:30-31, vibe/core/config.py:598-634
HTTP Header Injection
The GenericBackend handles the injection of authentication credentials into HTTP requests. It differentiates between standard API keys and OAuth tokens to apply the correct header format.
| Provider | Authentication Header | Beta/Version Headers |
|---|---|---|
| Mistral | Authorization: Bearer <KEY> | N/A |
| Anthropic (API) | x-api-key: <KEY> | anthropic-version: 2023-06-01 |
| Anthropic (OAuth) | Authorization: Bearer <TOKEN> | anthropic-beta: oauth-2025-04-20 |
| Qwen (OAuth) | Authorization: Bearer <TOKEN> | N/A |
Sources: vibe/core/llm/backend/generic.py:127-130, vibe/core/llm/backend/generic.py:300-309, vibe/core/llm/backend/generic.py:489-516
Onboarding and User Login
The setup flow provides a graphical interface (via Textual) for selecting providers and entering credentials.
- Interactive Selector: Users cycle through providers like Mistral, Anthropic, or Local.
- Validation: The
ApiKeyScreenusesLengthvalidators to ensure keys are not empty before submission. - Automated Login: The
qqcode --login anthropicorqqcode --login qwencommands trigger the_login_anthropic_asyncor_login_qwen_asyncfunctions respectively to bypass the full onboarding TUI.
Sources: vibe/setup/onboarding/screens/api_key.py:52-110, vibe/cli/login.py:19-125
Conclusion
The Authentication & OAuth system provides a robust framework for managing diverse credential types. By utilizing a hierarchy of configuration sources—from environment variables to persistent TOML storage—the project ensures that LLM interaction remains secure while offering a user-friendly setup experience. The specialized OAuth implementations for Anthropic and Qwen demonstrate the system's extensibility for modern API security standards.