---
summary: "Azure OpenAI provider: API key, endpoint, and deployment validation probe."
read_when:
  - 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:

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

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

```json
{
  "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:

```http
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: 64`. This small total completion budget leaves room for hidden reasoning tokens while keeping
the validation probe bounded. Dated API versions continue to request at most one output token.

```http
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, potentially billable inference request. The 64-token
v1 budget is a maximum, not automatic consumption; the deployment can consume fewer input and output tokens.

## 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

```bash
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`
