codex auth verify-flagged

Re-test accounts that were previously flagged as unhealthy and optionally restore them if they’re working again.

Usage

codex auth verify-flagged [--dry-run] [--json] [--no-restore]

--dry-run

boolean

default:"false"

Preview which accounts would be restored without making changes.

--json

boolean

default:"false"

Output machine-readable JSON instead of human-friendly text.

--no-restore

boolean

default:"false"

Verify only - do not restore healthy flagged accounts.

What Are Flagged Accounts?

Accounts are moved to the flagged list when:

Token refresh fails with hard failures:
- invalid_grant - Refresh token revoked
- invalid_client - OAuth client issue
- unauthorized_client - Authorization removed
- Account deletion or email change
Consecutive failures exceed threshold (typically 3)
Manual flagging via dashboard (Delete → Move to Flagged)

Flagged accounts are stored in:

~/.codex/multi-auth/openai-codex-flagged-accounts.json

How It Works

Loads all flagged accounts
Attempts token refresh for each account
Tests access token validity
Optionally performs live quota probe
Restores healthy accounts back to main pool (unless --no-restore)
Updates flagged list with verification timestamps

Example Output

Default Mode (Restore Enabled)

Verifying 3 flagged account(s)...
  ✓ [email protected] | restored (was: invalid_grant, now: working)
  ✗ [email protected] | still broken (invalid_grant)
  ! [email protected] | refresh succeeded but rate-limited

Result: 1 restored | 1 still broken | 1 warning

Dry Run Mode

Verifying 3 flagged account(s) (dry run)...
  ✓ [email protected] | would restore (was: invalid_grant, now: working)
  ✗ [email protected] | would remain flagged (invalid_grant)

Result (dry run): 1 would restore | 1 would remain flagged

Verify-Only Mode (`--no-restore`)

Verifying 3 flagged account(s) (verify only)...
  ✓ [email protected] | healthy (but not restored: --no-restore)
  ✗ [email protected] | still broken (invalid_grant)

Result: 1 healthy | 1 still broken | 0 restored

JSON Output

codex auth verify-flagged --json

{
  "total": 3,
  "verified": 3,
  "restored": 1,
  "stillBroken": 1,
  "warnings": 1,
  "accounts": [
    {
      "email": "[email protected]",
      "accountId": "user-abc123",
      "status": "restored",
      "previousReason": "invalid_grant",
      "currentStatus": "working"
    },
    {
      "email": "[email protected]",
      "accountId": "user-def456",
      "status": "still_broken",
      "reason": "invalid_grant"
    },
    {
      "email": "[email protected]",
      "accountId": "user-ghi789",
      "status": "warning",
      "reason": "rate_limited"
    }
  ]
}

Restoration Criteria

An account is restored if:

Token refresh succeeds - New access token obtained
Access token is valid - Not expired or malformed
No active rate limits - Not currently cooling down
Not in --no-restore mode
Not a dry run

Exit Codes

exit code

All flagged accounts verified (restored or confirmed broken)

exit code

Verification failed (storage errors, network issues)

Examples

Verify and restore

codex auth verify-flagged

Preview restorations

codex auth verify-flagged --dry-run

Check status without restoring

codex auth verify-flagged --no-restore

Machine-readable check

codex auth verify-flagged --json | jq '.restored'

Automated recovery

#!/bin/bash
# Verify flagged accounts daily
codex auth verify-flagged --json > flagged-report.json

# Alert if any restored
if [ $(jq '.restored' flagged-report.json) -gt 0 ]; then
  echo "Some flagged accounts were restored"
  codex auth check --live
fi

Why Accounts Get Flagged

Common Reasons

Password changed - User changed ChatGPT password
Token revoked - Manual token revocation in ChatGPT settings
Account deleted - ChatGPT account deleted
OAuth app removed - User removed OAuth authorization
Email changed - Primary email address changed

Temporary Failures (Not Flagged)

These failures do NOT flag accounts:

Network timeouts
Rate limit errors (429)
Server errors (5xx)
Temporary auth service outages

Restoration Impact

When an account is restored:

Moved back to main pool - openai-codex-accounts.json
Health score reset - Starts at 100
Cooldowns cleared - Rate limit timers reset
Metadata updated - Email, account ID refreshed
Flagged entry removed - Deleted from openai-codex-flagged-accounts.json

Best Practices

Regular Verification

Run weekly to catch recovered accounts:

# Cron: Every Sunday at 3 AM
0 3 * * 0 codex auth verify-flagged

Before Important Work

Check flagged accounts before long sessions:

codex auth verify-flagged
codex auth check --live
codex auth forecast --live

Dry Run First

Always preview in production:

codex auth verify-flagged --dry-run
# Review output
codex auth verify-flagged

Troubleshooting

No Flagged Accounts

No flagged accounts to verify.

This is good - all accounts are healthy.

All Verifications Fail

Network or auth service issue:

# Wait and retry
sleep 300
codex auth verify-flagged

Restored Account Immediately Fails

The account may have transient issues:

codex auth check
# If it fails again, manually remove it
codex auth login
# Dashboard → select account → D (delete permanently)

Storage Permission Denied

Check file permissions:

ls -la ~/.codex/multi-auth/openai-codex-flagged-accounts.json
chmod 600 ~/.codex/multi-auth/openai-codex-flagged-accounts.json

codex auth check - Health check active accounts
codex auth fix - Repair storage and accounts
codex auth doctor - Full diagnostics including flagged accounts
codex auth report - Include flagged accounts in report
codex auth login - Manually restore accounts via dashboard

Storage Files

Flagged Accounts Storage

{
  "version": 1,
  "accounts": [
    {
      "accountId": "user-abc123",
      "email": "[email protected]",
      "refreshToken": "token-xyz...",
      "flaggedAt": 1709251200000,
      "flaggedReason": "invalid_grant",
      "lastVerified": 1709337600000,
      "verificationCount": 3
    }
  ]
}

Location: ~/.codex/multi-auth/openai-codex-flagged-accounts.json

Verification Metadata

Each verification updates:

lastVerified - Timestamp of last verification attempt
verificationCount - Total verification attempts
Status outcome (still broken, restored, etc.)

Commands

Configuration

Dashboard

Usage

What Are Flagged Accounts?

How It Works

Example Output

Default Mode (Restore Enabled)

Dry Run Mode

Verify-Only Mode (`--no-restore`)

JSON Output

Restoration Criteria

Exit Codes

Examples

Verify and restore

Preview restorations

Check status without restoring

Machine-readable check

Automated recovery

Why Accounts Get Flagged

Common Reasons

Temporary Failures (Not Flagged)

Restoration Impact

Best Practices

Regular Verification

Before Important Work

Dry Run First

Troubleshooting

No Flagged Accounts

All Verifications Fail

Restored Account Immediately Fails

Storage Permission Denied

Storage Files

Flagged Accounts Storage

Verification Metadata

Build docs developers (and LLMs) love

Commands

Configuration

Dashboard

​Usage

​What Are Flagged Accounts?

​How It Works

​Example Output

​Default Mode (Restore Enabled)

​Dry Run Mode

​Verify-Only Mode (--no-restore)

​JSON Output

​Restoration Criteria

​Exit Codes

​Examples

​Verify and restore

​Preview restorations

​Check status without restoring

​Machine-readable check

​Automated recovery

​Why Accounts Get Flagged

​Common Reasons

​Temporary Failures (Not Flagged)

​Restoration Impact

​Best Practices

​Regular Verification

​Before Important Work

​Dry Run First

​Troubleshooting

​No Flagged Accounts

​All Verifications Fail

​Restored Account Immediately Fails

​Storage Permission Denied

​Related Commands

​Storage Files

​Flagged Accounts Storage

​Verification Metadata

Build docs developers (and LLMs) love

Usage

What Are Flagged Accounts?

How It Works

Example Output

Default Mode (Restore Enabled)

Dry Run Mode

Verify-Only Mode (`--no-restore`)

JSON Output

Restoration Criteria

Exit Codes

Examples

Verify and restore

Preview restorations

Check status without restoring

Machine-readable check

Automated recovery

Why Accounts Get Flagged

Common Reasons

Temporary Failures (Not Flagged)

Restoration Impact

Best Practices

Regular Verification

Before Important Work

Dry Run First

Troubleshooting

No Flagged Accounts

All Verifications Fail

Restored Account Immediately Fails

Storage Permission Denied

Related Commands

Storage Files

Flagged Accounts Storage

Verification Metadata