# AI Provider Authentication

AI Provider Authentication connects CoderFlow to Claude (Anthropic), Codex (OpenAI), and Gemini (Google) using OAuth. This enables agents to run tasks using your existing subscriptions to these services without managing API keys.

> **Note**: CoderFlow is completely functional using only OAuth authentication, but be aware that certain features like automatic task naming require at least one API key to be defined.

## 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 for each provider is used when launching tasks, and you can leave a provider with no active account selected.

## Connecting Accounts

Navigate to **Settings → Provider Authentication** to manage AI provider accounts.

### Adding an Account

1. Click **Add Account** next to the provider you want to connect (Claude, Codex, or Gemini)
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
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.

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

### 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 **Settings → Agent Keep-Alive**:

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

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

## CLI Compatibility

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

- Claude: `~/.claude/.credentials.json`
- Codex: `~/.codex/auth.json`
- Gemini: `~/.gemini/oauth_creds.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.

## 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 **Settings → Provider Authentication**.

### Authentication Expired

If you see authentication errors during task execution:
1. Check if the account still appears in Provider Authentication
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.
