---
summary: 'How Peekaboo handles OAuth for OpenAI/Codex and Anthropic (Claude Pro/Max)'
read_when:
  - 'adding or debugging OAuth logins for OpenAI or Anthropic'
  - 'explaining where tokens are stored and how they refresh'
---

# OAuth flows (OpenAI/Codex and Anthropic Max)

Peekaboo supports OAuth for two providers:
- **OpenAI/Codex** via `peekaboo config login openai`
- **Anthropic Claude Pro/Max** via `peekaboo config login anthropic`

These flows avoid storing API keys and instead keep refresh/access tokens in `~/.peekaboo/credentials` (chmod 600).

> Peekaboo shares the same credential layout as Tachikoma. Hosts can swap the profile directory (`TachikomaConfiguration.profileDirectoryName`) but **never copy environment keys into the file**; only explicit `config add`/`config login` writes.

## What happens during login
1. Generate PKCE values and open the provider’s authorize URL in the browser (also printed for headless use).
2. You paste the returned `code` (and `state` when required) into the CLI.
3. Peekaboo exchanges the code for `refresh` + `access` tokens and stores:
   - `OPENAI_REFRESH_TOKEN`, `OPENAI_ACCESS_TOKEN`, `OPENAI_ACCESS_EXPIRES` **or**
   - `ANTHROPIC_REFRESH_TOKEN`, `ANTHROPIC_ACCESS_TOKEN`, `ANTHROPIC_ACCESS_EXPIRES`
4. No API key is written for OAuth flows.

## How requests are sent
- Providers resolve OAuth tokens and API keys through the shared Tachikoma credential manager. If the access token is expired, Peekaboo refreshes once per request and updates the credentials file.
- Anthropic requests include the beta header used for Claude Max: `anthropic-beta: oauth-2025-04-20,claude-code-20250219,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14`.
- If OAuth tokens are absent but an API key exists, the provider falls back to the API-key path.
- OpenAI/Codex OAuth tokens may still be rejected by OpenAI API endpoints if the issued token lacks platform API scopes such as model or Responses access. In that case, use `peekaboo config add openai <api-key>` / `OPENAI_API_KEY` for `see --analyze`, `image --analyze`, and agent runs until the OAuth client is granted the required scopes.

## Validating connectivity
- `peekaboo config show --timeout 30` pings each configured provider and reports status (`ready (validated)`, `stored (validation failed: <reason>)`, `missing`).
- `peekaboo config add <provider> <secret>` validates immediately; failures are stored but warned.

## Revoking access
- **OpenAI/Codex**: revoke from your OpenAI account security page; then delete the stored tokens (`peekaboo config edit` or remove the keys from `~/.peekaboo/credentials`).
- **Anthropic**: revoke from your Claude account; remove the stored tokens the same way.

## Headless / CI
- If the browser cannot open, the CLI still prints the authorize URL; paste the resulting code back. Access/refresh storage and refresh logic are identical.

## Troubleshooting
- If validation fails after login, run `peekaboo config show --timeout 10 --verbose` to see the provider error.
- OpenAI errors mentioning missing scopes are server-side OAuth scope failures, not local credential loading failures. Configure an API key for API-backed OpenAI features.
- Stale access tokens are refreshed automatically; if refresh fails, rerun `peekaboo config login <provider>`.
