# How to Set Up OAuth for AI Providers in CodexBar: A Complete Configuration Guide

> Configure OAuth for AI providers like Codex, Claude, Gemini, and Vertex AI in CodexBar. This guide details credential management and token refreshing for seamless AI integration.

- Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar)
- Tags: how-to-guide
- Published: 2026-07-07

---

**CodexBar automatically manages OAuth authentication for Codex, Claude, Gemini, and Vertex AI through provider-specific credential stores that read JSON configuration files, interact with the macOS Keychain, and delegate to official CLIs to refresh tokens before they expire.**

CodexBar is a macOS menu bar application that aggregates usage metrics and billing information from multiple AI providers. Setting up OAuth for AI providers in CodexBar requires understanding how the app discovers existing credentials, validates token freshness, and orchestrates secure storage. This guide walks through the authentication flow as implemented in the steipete/CodexBar repository, covering manual CLI setup, automatic refresh mechanisms, and programmatic access patterns.

## How CodexBar Discovers and Loads OAuth Credentials

When CodexBar launches, each provider implementation checks for existing authentication through a cascading discovery process. The credential stores prioritize environment variables, then fall back to provider-specific JSON files in the home directory.

For **Codex** (OpenAI), the `CodexOAuthCredentialsStore.load` method in [`Sources/CodexBarCore/Providers/Codex/CodexOAuth/CodexOAuthCredentials.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/Codex/CodexOAuth/CodexOAuthCredentials.swift) (lines 65-78) parses `~/.codex/auth.json` created by the official `codex` CLI.

For **Claude** (Anthropic), `ClaudeOAuthCredentialsStore.loadFromEnvironment` in [`Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthCredentials.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthCredentials.swift) (lines 92-98) first checks for the `CODEXBAR_CLAUDE_OAUTH_TOKEN` environment variable, then reads `~/.claude/.credentials.json`.

## Provider-Specific Setup Instructions

### Codex (OpenAI-Compatible)

The Codex provider integrates with OpenAI's authentication system. To configure:

1. Install and authenticate the official Codex CLI:
   ```bash
   codex login
   ```

2. This creates `~/.codex/auth.json` containing your access token and refresh metadata.
3. CodexBar automatically detects this file on launch via `CodexOAuthCredentialsStore.load`.
4. The app monitors the `needsRefresh` property (defined in [`CodexOAuthCredentials.swift`](https://github.com/steipete/CodexBar/blob/main/CodexOAuthCredentials.swift), lines 31-35), which triggers when tokens are older than eight days.

### Claude (Anthropic)

Anthropic's Claude integration supports both CLI-generated and environment-based credentials:

1. Run the Claude CLI authentication:
   ```bash
   claude login
   ```

2. This writes credentials to `~/.claude/.credentials.json`.
3. Alternatively, set the environment variable before launching CodexBar:
   ```bash
   export CODEXBAR_CLAUDE_OAUTH_TOKEN=$(cat ~/.claude/.credentials.json | jq -r '.tokens.access_token')
   ```

When refresh is required, `ClaudeOAuthDelegatedRefreshCoordinator` contacts `https://platform.claude.com/v1/oauth/token` using the client ID defined in `defaultOAuthClientID`, while `ClaudeOAuthRefreshFailureGate` in [`ClaudeOAuthRefreshFailureGate.swift`](https://github.com/steipete/CodexBar/blob/main/ClaudeOAuthRefreshFailureGate.swift) handles failure scenarios.

### Gemini (Google)

Gemini follows the same `OAuthCredentialsStore` pattern as Codex but points to Google's token endpoints. Credentials are stored under `~/.config/gemini` and managed by `GeminiOAuthUsageFetcher`.

### Vertex AI (Google Cloud)

Vertex AI uses a different approach by shelling out to the Google Cloud SDK:

1. Ensure `gcloud` is installed and authenticated.
2. CodexBar executes `gcloud auth print-access-token` and caches the result in `VertexAIOAuthCredentialsStore`.
3. The token is refreshed automatically on a 60-minute TTL.

## Automatic Token Refresh and Persistence

CodexBar implements proactive token refresh to prevent authentication failures. Each provider uses distinct refresh logic:

- **Codex**: Checks if `last_refresh` exceeds eight days, then invokes the CLI's token refresh endpoint.
- **Claude**: Uses `ClaudeOAuthDelegatedRefreshCoordinator` to exchange refresh tokens via Anthropic's OAuth endpoint.
- **Vertex AI**: Refreshes every 60 minutes via `gcloud` command execution.

Refreshed credentials are persisted with restrictive permissions (`0600`). The `CodexOAuthCredentialsStore.save` method (lines 55-86) writes JSON back to disk, while Claude's `ClaudeOAuthCredentialsStore.writeMemoryCache` eventually calls `writePrivateFile` (lines 189-200) to ensure secure storage.

## Programmatic Access and Custom Integrations

Developers can interact with the credential stores directly for custom widgets or automation:

```swift
import CodexBarCore

do {
    // Load existing credentials
    let creds = try CodexOAuthCredentialsStore.load()
    // Force a refresh (use the public API)
    let refreshed = try CodexOAuthCredentialsStore.save(creds)
    print("New access token: \(creds.accessToken)")
} catch {
    print("OAuth error: \(error)")
}

```

For Claude environment variable access:

```swift
let credentials = try? ClaudeOAuthCredentialsStore.loadFromEnvironment(ProcessInfo.processInfo.environment)
print(credentials?.accessToken ?? "No token")

```

To verify CLI initialization:

```bash

# First login – creates ~/.claude/.credentials.json

claude login

# Verify that CodexBar can read it

codexbar status --provider claude

```

## Summary

- CodexBar supports OAuth for **Codex**, **Claude**, **Gemini**, and **Vertex AI** through dedicated credential stores in `Sources/CodexBarCore/Providers/`.
- Credentials are discovered via environment variables first, then JSON files in `~/.codex`, `~/.claude`, or `~/.config/gemini`.
- Automatic refresh occurs every **eight days** for Codex and via **delegated coordinators** for Claude, with tokens persisted using `0600` permissions.
- The `CodexOAuthUsageFetcher` and `ClaudeOAuthUsageFetcher` classes handle API authentication for usage metrics retrieval.
- Developers can programmatically access credentials using `CodexOAuthCredentialsStore.load()` and `ClaudeOAuthCredentialsStore.loadFromEnvironment()`.

## Frequently Asked Questions

### Where does CodexBar store OAuth credentials?

CodexBar stores credentials in provider-specific JSON files: `~/.codex/auth.json` for Codex, `~/.claude/.credentials.json` for Claude, and `~/.config/gemini` for Gemini. These files are created by the official CLIs (`codex login`, `claude login`) and are read by methods like `CodexOAuthCredentialsStore.load` and `ClaudeOAuthCredentialsStore.load` in the respective credential store implementations.

### How do I force a token refresh in CodexBar?

For Codex, you can programmatically trigger a refresh by calling `CodexOAuthCredentialsStore.save()` after loading the credentials, or simply delete the existing token file and re-run `codex login`. For Claude, the `ClaudeOAuthDelegatedRefreshCoordinator` handles automatic refresh when the token expires, but you can also set the `CODEXBAR_CLAUDE_OAUTH_TOKEN` environment variable to override the cached value temporarily.

### Can I use environment variables instead of credential files?

Yes. CodexBar checks environment variables before falling back to JSON files. For Claude, set `CODEXBAR_CLAUDE_OAUTH_TOKEN` to the access token string. The `ClaudeOAuthCredentialsStore.loadFromEnvironment` method specifically checks `ProcessInfo.processInfo.environment` for this variable, allowing temporary authentication without persistent file storage.

### What happens when my OAuth token expires?

CodexBar implements automatic refresh mechanisms. For Codex, the `needsRefresh` property (checking if the token is older than eight days) triggers CLI-based refresh. For Claude, the `ClaudeOAuthRefreshFailureGate` and `ClaudeOAuthDelegatedRefreshCoordinator` manage the OAuth token exchange with Anthropic's platform endpoint. If refresh fails, the app marks the provider as unauthenticated until manual CLI re-authentication occurs.