Skip to main content

AI Provider Authentication

AI Provider Authentication connects CoderFlow to Claude (Anthropic), Codex (OpenAI), Gemini (Google), Bob (IBM), and Grok (xAI) using OAuth or API-key accounts. This enables agents to run tasks using your existing subscriptions to these services without sharing raw credentials with users.

Note: CoderFlow is completely functional using OAuth authentication for task execution. API-key accounts are needed for API-backed helper features such as automatic task naming and setup-repository commit-message generation.

Overview​

CoderFlow supports multiple accounts per provider, allowing teams to:

  • Connect different accounts for different purposes (e.g., production vs. development)
  • Share provider access across the team without sharing credentials
  • Switch between accounts as needed
  • Automatically refresh tokens to maintain continuous access

Provider authentication is configured globally and applies to all environments. The active account or the configured round-robin pool for each provider is used when launching tasks, and you can leave a provider with no active account selected.

Connecting Accounts​

Navigate to Server Settings → AI Providers to manage AI provider accounts.

Adding an Account​

  1. Click Add Account next to the provider you want to connect (Claude, Codex, Gemini, Bob, or Grok)
  2. Optionally enter a label to identify this account (e.g., "Production", "Team Account")
  3. Click Start Sign-In to open the provider's authentication page
  4. Complete the sign-in process in your browser:
    • Claude: Sign in and copy the authorization code displayed
    • Codex/Gemini: Sign in and copy the URL from your browser's address bar after the redirect
    • Grok: Sign in on the displayed x.ai device-code page, confirm the user code, then return to CoderFlow and click I've signed in
  5. Paste the code or URL into CoderFlow and click Complete Sign-In

The account will appear in your provider list. If this is your first account for that provider, it becomes the active account automatically.

Adding an API Key Account​

API-key accounts are useful when you want CoderFlow to inject provider API keys into task containers or use provider APIs for helper features. Click Add Account, choose the API Key tab, enter a label and key, then save the account.

API-key accounts can also use a Custom Endpoint. Turn on Custom Endpoint and enter the endpoint's Base URL. Codex and Gemini accounts also accept an optional API Version. CoderFlow normalizes the endpoint and only sends custom endpoint environment variables when that API-key account is selected for the provider.

Common custom endpoint uses include:

  • Azure or proxy-hosted Responses-compatible endpoints for Codex
  • Anthropic-compatible gateways or on-prem proxies for Claude
  • Gemini-compatible gateways
  • Bob Shell endpoints that should receive BOBSHELL_API_BASE_URL

Custom endpoints apply to task execution and to API-backed helpers such as task-name or commit-message generation when the helper uses that provider.

Endpoint Type Presets​

Codex API-key accounts expose Endpoint Type presets so CoderFlow can build the Codex CLI provider config correctly. Codex CLI only speaks the OpenAI Responses API — chat-completions support was removed upstream in early 2026 (discussion #7782). All presets therefore wire to responses:

  • Default provider endpoint: Use the Codex CLI's built-in provider behavior.
  • Responses-compatible hosted: For hosted endpoints that speak the OpenAI Responses API. In practice this means a LiteLLM proxy in front of OpenRouter / Together / Groq / Fireworks, or any other Responses-speaking gateway. Direct OpenRouter/Together/etc. URLs no longer work because they only speak Chat Completions.
  • Local Responses-compatible: For local servers that speak the Responses API. LM Studio is the most common option (native Responses support, default port 1234). vLLM and Ollama do not yet support Responses; front them with a LiteLLM proxy.
  • Azure OpenAI: For Azure OpenAI resources. CoderFlow rewrites the runtime base URL to the Codex CLI /v1/responses shape automatically. API version is optional metadata; the v1 API surface does not require it.
  • Custom endpoint: Generic advanced override. The URL must speak the OpenAI Responses API.

If a hosted OSS provider (OpenRouter, Together, Groq, DeepInfra…) is what you want to use, see Walkthrough A below.

Before You Go Down the OSS Path​

CoderFlow's first-class path is the Claude / Codex / Gemini subscriptions — they deliver the best results for the kind of multi-file, agentic coding work CoderFlow exists to support. Pursue open-source models only when you have a specific reason: a compliance requirement against the major providers, an air-gapped environment, or a per-task cost target the hosted subscriptions don't meet. For everyone else, OSS will be a downgrade in tool-call quality, multi-step planning, and refactor success rates.

If you've decided OSS is the right call, the walkthroughs below cover the two realistic paths.

Walkthrough A: Hosted OSS via OpenRouter (LiteLLM in front)​

Use this path to drive frontier-class OSS models (Qwen3-Coder, DeepSeek V3.1, Kimi K2, GLM 4.5) without owning GPU hardware. This is the production-realistic option for OSS use. Since Codex requires the Responses API but OpenRouter only speaks Chat Completions, you run a small LiteLLM proxy that translates between them. LiteLLM lives outside CoderFlow — typically as a single Docker container on the same host as the server.

This walkthrough configures the server-wide Codex account and model. Per-user overrides live under Profile Settings → AI Providers (same forms, scoped to the signed-in user); per-environment model overrides live under Environments.

  1. Get an OpenRouter API key. Sign up at openrouter.ai, add credit, and create a key (format: sk-or-…). Frontier OSS models run cents-per-task; budget accordingly for sustained use.
  2. Write a LiteLLM config at litellm-config.yaml: 
    model_list:
      - model_name: qwen3-coder
        litellm_params:
          model: openrouter/qwen/qwen3-coder
          api_key: os.environ/OPENROUTER_API_KEY
      - model_name: deepseek-v3.1
        litellm_params:
          model: openrouter/deepseek/deepseek-v3.1
          api_key: os.environ/OPENROUTER_API_KEY
    The model_name keys are what you'll type in CoderFlow's Codex Model field; the litellm_params.model values are OpenRouter's identifiers.
  3. Run LiteLLM as a container: 
    docker run -d --name litellm -p 4000:4000 \
      -e OPENROUTER_API_KEY=sk-or-... \
      -v $PWD/litellm-config.yaml:/app/config.yaml \
      ghcr.io/berriai/litellm:main-latest \
      --config /app/config.yaml --port 4000
  4. Add a Codex API-key account in CoderFlow. Open Server Settings → AI Providers, click Add Account next to Codex, and choose the API Key tab. Label it OpenRouter (LiteLLM), then enable Custom Endpoint and fill in:
    • Endpoint Type: Local Responses-compatible
    • Base URL: http://host.docker.internal:4000/v1
    • API Key: any non-empty string unless you configured a master key in LiteLLM
  5. Save and Test. Connection-successful means task containers can reach LiteLLM and LiteLLM can reach OpenRouter.
  6. Mark Active, then in Server Settings → Models enter one of your LiteLLM model_name aliases (e.g. qwen3-coder) in the Codex Model field. Save.
  7. Launch a task with the Codex agent. Start with a small, low-stakes task to validate tool calls round-trip cleanly through the LiteLLM bridge before relying on it.

Caveats:

  • LiteLLM is separate infrastructure your team has to run somewhere. The one-container setup above is fine for a single developer or small team; multi-user deployments may want auth and observability layered on.
  • LiteLLM's Responses→Chat-Completions translation is not explicitly documented for OpenRouter as an upstream. The pieces fit on paper (LiteLLM exposes /v1/responses and auto-bridges to chat-completions providers, OpenRouter is OpenAI-style), but tool-call fidelity through the bridge isn't guaranteed. Verify with a trivial task first.
  • Some OSS models do not produce well-formed tool calls regardless of the proxy. Qwen3-Coder, DeepSeek V3.1, and Kimi K2 are the most reliable choices for agentic coding in early 2026.

Walkthrough B: Local OSS via LM Studio (Smoke Tests / Air-Gapped)​

This path is useful for smoke-testing the Responses-API wiring, running offline or air-gapped, or handling trivial single-file tasks on local hardware. It is not production-grade for serious coding work unless you're running a workstation-class machine (M3 Max 128 GB unified, RTX 4090 + 64 GB RAM, etc.) with a 30B+ quantized coding model — and even then, expect a meaningful capability gap vs. the hosted frontier models from Walkthrough A or the Claude / Codex subscriptions.

LM Studio speaks the Responses API natively, so no proxy or translation layer is needed.

  1. Install LM Studio from lmstudio.ai on the machine that will host the model (typically the same host that runs CoderFlow).
  2. Download a coding model in LM Studio. Pick the largest variant your hardware can fit comfortably — Qwen3-Coder 32B-quantized is the practical floor for tool-call reliability; 7B-14B models will frequently mangle agentic flows.
  3. Start the server. In LM Studio, switch to the Developer tab and click Start Server. By default it listens on http://localhost:1234/v1. Note the model identifier shown in the loaded model card — you'll need it in step 6.
  4. Add a Codex API-key account in CoderFlow. Open Server Settings → AI Providers, click Add Account next to Codex, and choose the API Key tab. Give it a label like LM Studio, then enable Custom Endpoint and fill in:
    • Endpoint Type: Local Responses-compatible
    • Base URL: http://host.docker.internal:1234/v1 (use host.docker.internal so task containers can reach the LM Studio server on the host)
    • API Key: any non-empty string — LM Studio accepts anything by default
  5. Save the account, then Test it. A green "Connection successful" result confirms task containers can reach LM Studio.
  6. Mark the account Active, then go to Server Settings → Models and enter the LM Studio model ID in the Codex Model field. Click Save.
  7. Launch a task with the Codex agent. The first request will take a few seconds while LM Studio warms the model up.

Account Labels​

Labels help identify accounts when you have multiple connected. Good label examples:

  • Production
  • Development
  • Team Shared
  • Personal

If you don't provide a label, the account email address is used when available. For Claude (which doesn't expose email through OAuth), a timestamp-based label is generated.

Managing Accounts​

Setting the Active Account​

The active account (marked with a green checkmark and "Active" badge) is used for all task execution with that provider.

To change the active account, click the checkmark button next to the account you want to activate. Click the active account's checkmark button again to clear the selection entirely.

Changing or clearing the active account immediately affects new task launches. Running tasks continue using the account they started with.

Round-Robin OAuth Accounts​

OAuth accounts can be added to a provider's round-robin pool. Click the round-robin button next to each OAuth account you want CoderFlow to rotate through. API-key accounts cannot participate in round-robin selection.

For task launches, CoderFlow resolves accounts in this order:

  1. A user- or task-specific preferred account, when one is selected
  2. The active API-key account
  3. The next OAuth account in the round-robin pool
  4. The active OAuth account

The round-robin cursor advances as task credential profiles are prepared. This spreads new tasks across a team account pool while preserving the ability to pin a single account by making it active and leaving round robin disabled.

Renaming Accounts​

  1. Click the Edit (pencil) icon next to the account
  2. Enter a new label
  3. Click Save

Removing Accounts​

  1. Click the Delete (trash) icon next to the account
  2. Confirm the removal

If you remove the active account, no other account is auto-selected. Tasks using that provider will fail until you choose another active account or connect a new one.

Token Refresh​

OAuth tokens expire periodically. CoderFlow automatically refreshes tokens before they expire. Token refresh is managed by the Agent Keep-Alive service.

To configure token refresh, navigate to Server Settings → Agent Keepalive:

  • Enable/Disable: Toggle automatic refresh for each provider
  • Refresh Interval: Set how often to check and refresh tokens (1-24 hours)
  • Status: View the last refresh time and next scheduled refresh

Failed refreshes are retried up to 3 times. If token refresh fails repeatedly (e.g., if you revoked access from the provider), you may need to reconnect the account.

Provider-Specific Notes​

Claude (Anthropic)​

  • Uses Anthropic's OAuth flow with PKCE for security
  • Displays an authorization code that you copy back to CoderFlow
  • Email address is not available through OAuth (labels are especially useful)
  • Access includes Claude Code inference capabilities
  • An effort level (low, medium, high, xhigh, max) can be set per user, per environment, or per task; tasks pass it to the Claude Code CLI via --effort (env var: CLAUDE_CODE_EFFORT_LEVEL)

Codex (OpenAI)​

  • Uses OpenAI's OAuth flow with PKCE
  • Redirects to a URL that you copy back to CoderFlow
  • Email is extracted from the OAuth token
  • Provides access to ChatGPT subscription models

Gemini (Google)​

  • Uses Google's standard OAuth flow
  • Redirects to a URL that you copy back to CoderFlow
  • Email is fetched from Google's user info endpoint
  • Requires Google Cloud Platform access

Bob (IBM)​

  • Uses IBM Bob Shell authentication
  • Redirects through the Bob backend, which handles the OAuth flow
  • The test action validates the account by refreshing the Bob token
  • Task containers receive Bob credentials as a .bob profile; CoderFlow mounts the selected profile at /mnt/bob and copies it to /home/coder/.bob
  • If no selected provider profile directory exists and the server has a ~/.bob directory, CoderFlow can mount that directory as a fallback

Grok (xAI)​

  • Uses xAI's OIDC device-code flow (auth.x.ai), so no callback URL is required
  • CoderFlow displays both a sign-in URL and a short user code; sign in on any device, confirm the code, then click I've signed in
  • Email and name are fetched from the OIDC userinfo endpoint
  • Tokens are refreshed automatically; the test action validates by attempting a refresh
  • Task containers receive Grok credentials as a .grok profile; CoderFlow mounts the selected profile at /mnt/grok and copies it to /home/coder/.grok
  • An effort level can be set per account from the provider settings; tasks pass it to the Grok CLI via --effort. Valid values depend on the selected model: grok-4.3 accepts low (default), medium, high; grok-4.20-multi-agent-0309 accepts low, medium, high, xhigh (controls parallel agent count rather than depth)

CLI Compatibility​

CoderFlow maintains compatibility with Claude Code, Codex CLI, Gemini CLI, Bob Shell, and Grok Build by synchronizing the active account's credentials to the standard CLI credential files where applicable:

  • Claude: ~/.claude/.credentials.json
  • Codex: ~/.codex/auth.json
  • Gemini: ~/.gemini/oauth_creds.json
  • Bob: ~/.bob/credentials.json
  • Grok: ~/.grok/auth.json

When you change the active account in CoderFlow, the CLI credential files are updated automatically. This allows you to use the CLI tools with the same account that CoderFlow is using.

Automatic Names and Commit Messages​

CoderFlow can call provider APIs for small helper tasks:

  • Automatic task names are generated from task instructions when the task form asks CoderFlow for a name.
  • Commit-message generation is available in the Environments and Skills git workflows.

Both helpers use the server-level Default Agent from setup configuration, not the environment's task-specific agent selection. Change it in Server Settings → General Settings → Default Agent when you want helper calls to use a different provider. The helper then uses the selected provider's auxiliary API-key account; if that account has a custom endpoint, the helper uses the custom endpoint too. For custom endpoints, CoderFlow uses the configured model for that provider so the request matches the deployed model behind the endpoint.

The implemented API helper paths are Claude, Codex, and Gemini. Bob and Grok are available for task execution, OAuth, and API-key injection, but these API helper calls do not currently use them.

Troubleshooting​

"Provider not configured" Error​

This error appears when launching tasks if no account is connected for the required provider, or if all connected accounts are currently unselected. Connect an account or mark one active in Server Settings → AI Providers.

Authentication Expired​

If you see authentication errors during task execution:

  1. Check if the account still appears under AI Providers
  2. Try removing and re-adding the account
  3. Verify your subscription is still active with the provider

Token Refresh Failures​

Check the server logs for refresh errors. Common causes:

  • Provider subscription expired
  • Access revoked from provider's settings
  • Network connectivity issues

Re-authenticate by removing and re-adding the account to get fresh tokens.