# Authentication Methods DBX Supports When Connecting to AI Providers

> Learn authentication methods DBX supports for AI providers. Explore API key and Bearer token options for seamless integration and enhanced security.

- Repository: [skyler/dbx](https://github.com/t8y2/dbx)
- Tags: api-reference
- Published: 2026-07-05

---

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

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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.