Authentication Methods DBX Supports When Connecting to AI Providers

DBX supports two authentication methods when connecting to AI providers: API key (api-key) and Bearer token (bearer), defined in the AiAuthMethod type within the desktop settings store.

The open-source t8y2/dbx project defines a strict authentication interface for integrating with large language model APIs. When configuring connections to providers like Claude, OpenAI, or Gemini, DBX uses the AiAuthMethod type to determine how credentials are transmitted in HTTP headers. Understanding these authentication methods is essential for securely connecting the application to both managed services and custom AI endpoints.

Supported Authentication Methods

The AiAuthMethod type is declared at line 19 of apps/desktop/src/stores/settingsStore.ts and supports exactly two values:

API Key Authentication

The api-key method transmits a plain API key in the request headers, typically using a header named api-key or similar. This method is used by providers that expect direct key-based access without OAuth-style formatting.

Bearer Token Authentication

The bearer method sends a Bearer token in the Authorization header using the standard format Authorization: Bearer <token>. This is the predominant method for modern AI services following OAuth 2.0 conventions.

Provider Preset Authentication Mappings

Each AI provider preset in DBX specifies its required authentication method via the authMethod field in the AI_PROVIDER_PRESETS configuration. The following table illustrates the mapping between providers and their authentication requirements:

Provider	Authentication Method	Notes
Claude	api-key	Requires explicit API key
OpenAI	bearer	Standard Bearer token authentication
Gemini	api-key	Google's API key format
DeepSeek	bearer	OAuth-style Bearer tokens
Qwen	bearer	Alibaba Cloud Bearer authentication
Ollama	bearer	requiresApiKey: false (local deployment)
OpenAI-compatible	bearer	Generic OpenAI API compatibility
Codex CLI	bearer	No API key required
Custom	bearer	Requires API key despite Bearer method

These presets are defined in apps/desktop/src/stores/settingsStore.ts between lines 20-100, with the authMethod field formally defined in the AiConfig interface at line 25.

Configuring Authentication in Practice

The normalizeAiConfig function and useSettingsStore composable provide programmatic interfaces for managing these authentication configurations.

Creating a Configuration with Explicit Authentication

To manually create an AI configuration with a specific authentication method, use the normalizeAiConfig helper:

import { normalizeAiConfig } from "@/stores/settingsStore";

const openAiConfig = normalizeAiConfig({
  provider: "openai",
  endpoint: "https://api.openai.com/v1/chat/completions",
  model: "gpt-4o-mini",
  apiKey: "sk-my-openai-token",
  authMethod: "bearer",          // ← explicit bearer authentication
});

console.log(openAiConfig);

Switching Providers and Authentication Methods

When switching between providers with different authentication requirements, the settings store automatically handles the transition:

import { useSettingsStore } from "@/stores/settingsStore";

const store = useSettingsStore();

// Switch from Claude (api-key) to OpenAI (bearer)
store.updateAiConfig({ provider: "openai" });

// The store now holds a Bearer-authenticated config:
console.log(store.aiConfig.value.authMethod); // "bearer"

Validating Configuration Completeness

Before making API calls, verify that all required fields—including the authentication credentials—are present:

import { useSettingsStore } from "@/stores/settingsStore";

const store = useSettingsStore();

if (store.isConfigured()) {
  console.log("All required fields (endpoint, model, and auth) are present.");
} else {
  console.log("Missing endpoint/model or API key for the selected provider.");
}

Custom Providers with Specific Authentication

For custom AI endpoints, explicitly set the authentication method to match your service requirements:

import { normalizeAiConfig } from "@/stores/settingsStore";

const customConfig = normalizeAiConfig({
  provider: "custom",
  endpoint: "https://my-ai.example.com/v1",
  model: "my-model",
  apiKey: "my-secret-key",
  authMethod: "api-key",   // choose the API-key method for this custom service
});

Implementation Architecture

The authentication method selection flows through three critical components:

1. Configuration Layer: apps/desktop/src/stores/settingsStore.ts defines the AiAuthMethod union type and AiConfig interface, storing the authMethod field alongside the apiKey value.

2. Validation Layer: packages/app-tests/settingsStore.test.ts contains unit tests verifying that each provider preset declares the correct authMethod (e.g., assert.equal(AI_PROVIDER_PRESETS.openai.authMethod, "bearer")).

3. Transport Layer: apps/desktop/src/lib/backend/api.ts implements the actual HTTP client logic, constructing request headers based on the aiConfig.authMethod value—either injecting the raw API key or formatting the Bearer token in the Authorization header.

Summary

• DBX supports exactly two authentication methods when connecting to AI providers: API key (api-key) and Bearer token (bearer).
• The AiAuthMethod type in apps/desktop/src/stores/settingsStore.ts enforces this binary choice at the TypeScript level.
• Provider presets (Claude, OpenAI, Gemini, etc.) hardcode their preferred authentication method in the AI_PROVIDER_PRESETS configuration object.
• The authMethod field in AiConfig determines how the API client in apps/desktop/src/lib/backend/api.ts constructs the HTTP Authorization header.
• Use normalizeAiConfig() to programmatically create configurations with specific authentication methods, and useSettingsStore() to manage runtime configuration state.

Frequently Asked Questions

What authentication methods does DBX support for AI providers?

DBX supports two authentication methods: API key (api-key) and Bearer token (bearer). These are defined in the AiAuthMethod type located in apps/desktop/src/stores/settingsStore.ts. The API key method sends credentials in a dedicated header, while the Bearer method uses the standard Authorization: Bearer <token> format.

How do I configure Bearer token authentication for OpenAI in DBX?

When configuring an OpenAI provider, set the authMethod field to "bearer" in your configuration object. The AI_PROVIDER_PRESETS.openai preset automatically sets this value, so using normalizeAiConfig({ provider: "openai", apiKey: "sk-..." }) will default to Bearer authentication without manual specification.

Where is the authentication method stored in DBX?

The authentication method is stored in the authMethod property of the AiConfig interface, defined at line 25 of apps/desktop/src/stores/settingsStore.ts. This value persists in the desktop settings store and is accessed via useSettingsStore().aiConfig.value.authMethod at runtime.

Does DBX support custom authentication methods for AI providers?

No, DBX strictly supports only the two methods defined in AiAuthMethod: api-key and bearer. While you can configure a custom provider endpoint using the "custom" provider preset, you must choose between these two standard authentication methods; the system does not support arbitrary custom header schemes or OAuth flows beyond Bearer tokens.

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