OAuth Lifecycle in Production

OAuth is a runtime concern

The Agent SDK can run on the OAuth token from claude login — perfect for personal apps and Pro/Max-funded production. Production discipline: know where the token lives (Keychain on macOS, file on Linux), how to refresh it, what happens when it expires, and how to recover without manual intervention.

The Anthropic API key is reserved scaffolding

cwkPippa's stance: the Anthropic API key path exists as code (for symmetry, future switching) but is intentionally NOT a runtime path. The env value is forbidden from the running process so the sk-ant-* pattern cannot leak into JSONL logs. OAuth-only is a privacy posture, not just a billing one.

What 'OAuth failed' looks like

When the OAuth token is invalid or expired, the SDK raises an auth error. Handle it: log the failure, alert the operator, do not retry blindly. Token refresh is interactive (Anthropic decides when), so production needs an operator path — not a silent crash loop.

Principle: OAuth is convenient until it is not. Document the recovery path; do not let auth failure be a silent outage.

Code

Detect and surface OAuth failure·python

from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.errors import AuthenticationError

async def try_query(prompt: str):
    try:
        async for ev in query(prompt=prompt, options=ClaudeAgentOptions(cwd="/tmp")):
            yield ev
    except AuthenticationError as e:
        # Do NOT retry blindly — token is bad until operator refreshes.
        alert_operator(f"Claude OAuth failed: {e}")
        raise

Forbid the API key value (cwkPippa stance)·python

import os

if os.environ.get("ANTHROPIC_API_KEY", "").startswith("sk-ant-"):
    # Refuse to start; keep the value out of the running process.
    raise RuntimeError(
        "ANTHROPIC_API_KEY is set to a real key. Production runs on OAuth only;"
        " remove the env value so the sk-ant- pattern cannot leak into logs."
    )

OAuth is a runtime concern

The Anthropic API key is reserved scaffolding

What 'OAuth failed' looks like

Code

External links

Exercise

Progress

Comments 0