steipete--codexbar/docs/azure-openai.md

summary, read_when

summary	read_when
Azure OpenAI provider: API key, endpoint, and deployment validation probe.	Debugging Azure OpenAI provider setup Updating Azure OpenAI endpoint or deployment validation Explaining Azure OpenAI environment variables

Azure OpenAI provider

CodexBar's Azure OpenAI provider validates that a configured deployment is reachable. It does not read Azure spend, quota history, or token usage history.

Authentication

Azure OpenAI requires three values:

1. API key
2. Resource endpoint
3. Deployment name

Settings -> Providers -> Azure OpenAI stores those values in the shared CodexBar config. The same values can also be provided with environment variables:

export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_ENDPOINT="https://resource.openai.azure.com"
export AZURE_OPENAI_DEPLOYMENT_NAME="chat-prod"

You can store the API key through the CLI:

printf '%s' "$AZURE_OPENAI_API_KEY" | codexbar config set-api-key --provider azure-openai --stdin

The endpoint and deployment are stored as enterpriseHost and workspaceID in the azureopenai provider config:

{
  "id": "azureopenai",
  "apiKey": "<AZURE_OPENAI_API_KEY>",
  "enterpriseHost": "https://resource.openai.azure.com",
  "workspaceID": "chat-prod"
}

Data source

CodexBar sends a minimal chat-completions request to validate the deployment:

POST https://resource.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=2024-10-21
api-key: <api key>
Accept: application/json
Content-Type: application/json

For dated API versions, the request body contains one ping message and max_tokens: 1. A successful response is parsed only for the returned model field so the menu can show deployment detail.

Set AZURE_OPENAI_API_VERSION to override the API version. When it is set to v1, CodexBar uses Azure's OpenAI-compatible v1 path, includes the deployment name as the request model, and uses max_completion_tokens: 1:

POST https://resource.openai.azure.com/openai/v1/chat/completions

Endpoint handling

AZURE_OPENAI_ENDPOINT and the configured endpoint field must be HTTPS URLs, or bare hosts that can be normalized to HTTPS. CodexBar rejects explicit http:// endpoints, user info, and encoded host-delimiter tricks before attaching the api-key header.

Endpoint paths are preserved. CodexBar avoids duplicating a trailing /openai for dated API versions or a trailing /openai/v1 for the v1 API when building the validation URL.

Each refresh with complete, valid configuration sends this real inference request and can consume billable input and output tokens for the configured deployment.

Display

• Settings shows the provider's static api label before a fetch. After a successful fetch, Settings' Source row and the CLI report deployment.
• The menu shows the Azure OpenAI resource host as organization context.
• The primary detail line shows Deployment: <name> and includes Model: <model> when the validation response returns one.
• The menu bar usage meter does not show spend, quota, or reset history because the provider only performs deployment validation.

CLI usage

codexbar usage --provider azure-openai
codexbar usage --provider azureopenai
codexbar usage --provider aoai

Key files

• Sources/CodexBarCore/Providers/AzureOpenAI/AzureOpenAIProviderDescriptor.swift
• Sources/CodexBarCore/Providers/AzureOpenAI/AzureOpenAISettingsReader.swift
• Sources/CodexBarCore/Providers/AzureOpenAI/AzureOpenAIUsageFetcher.swift
• Sources/CodexBar/Providers/AzureOpenAI/AzureOpenAIProviderImplementation.swift
• Tests/CodexBarTests/AzureOpenAIUsageFetcherTests.swift