Headroom Authentication Modes for LLM Providers: PAYG, OAuth, and Subscription

Headroom supports three distinct authentication modes—PAYG (Pay-as-you-go), OAuth, and Subscription—to classify inbound LLM provider requests and determine appropriate compression policies.

The chopratejas/headroom proxy implements a robust authentication mode classifier that distinguishes between API key types and client identities without performing any I/O operations. This classification system lives in headroom/proxy/auth_mode.py and drives critical decisions about request header mutation and compression strategies.

The Three Headroom Authentication Modes

The AuthMode enum defines three mutually exclusive categories that cover the full spectrum of LLM provider authentication schemes.

PAYG (Pay-as-you-go)

PAYG mode identifies standard API key authentication used by individual developers and pay-as-you-go accounts. When requests contain standard API keys, Headroom applies aggressive live-zone compression to optimize bandwidth.

The classifier detects PAYG mode through these header patterns:

• x-api-key or x-goog-api-key headers present
• Authorization: Bearer sk-ant-api* (Anthropic API keys)
• Generic Bearer sk-* tokens (OpenAI, Gemini, and other providers)

OAuth

OAUTH mode handles structured bearer tokens and delegated authentication schemes. This mode restricts compression to lossless-only transformations to preserve token integrity and avoid breaking signed requests.

Detection triggers include:

• Authorization: Bearer sk-ant-oat-* (Claude Pro OAuth style tokens)
• JWT-style bearer tokens matching the header.payload.signature pattern
• Any Authorization header that does not match standard API key patterns (e.g., AWS SigV4, Basic auth)

Subscription

SUBSCRIPTION mode identifies subscription-bound CLI and IDE clients that require full header preservation. In this mode, Headroom does not mutate request headers or user-agent details, ensuring compatibility with licensed client software.

The classifier recognizes subscription clients by inspecting the User-Agent header for known prefixes defined in SUBSCRIPTION_UA_PREFIXES, including:

• claude-cli/
• codex-cli/
• github-copilot/

How the Auth Mode Classifier Works

The classification logic resides in the classify_auth_mode function within headroom/proxy/auth_mode.py (lines 11‑80). This function operates entirely in-memory, analyzing incoming request headers to determine the appropriate AuthMode enum value.

The classifier follows a precedence-based detection strategy:

1. User-Agent inspection for subscription prefixes
2. Authorization header parsing for OAuth patterns
3. API key detection for PAYG classification
4. Default fallback to PAYG when no recognizable signals are present

This default to PAYG represents a safety-first design: incorrectly classified requests can be safely re-run, whereas misclassifying a subscription client could trigger revocation of user licenses.

Classifying Authentication Modes in Practice

The classify_auth_mode function accepts a headers dictionary and returns the appropriate AuthMode enum member.

from headroom.proxy.auth_mode import classify_auth_mode, AuthMode

# Example 1 – OpenAI API key (PAYG)

headers = {"authorization": "Bearer sk-abcdef123"}
mode = classify_auth_mode(headers)
assert mode is AuthMode.PAYG
print(f"Mode: {mode}")   # → Mode: payg

# Example 2 – Claude Pro OAuth token (OAUTH)

headers = {"authorization": "Bearer sk-ant-oat-xyz"}
mode = classify_auth_mode(headers)
assert mode is AuthMode.OAUTH
print(f"Mode: {mode}")   # → Mode: oauth

# Example 3 – Subscription CLI client (SUBSCRIPTION)

headers = {"user-agent": "claude-cli/1.2.3"}
mode = classify_auth_mode(headers)
assert mode is AuthMode.SUBSCRIPTION
print(f"Mode: {mode}")   # → Mode: subscription

# Example 4 – Fallback when nothing matches (defaults to PAYG)

headers = {}
mode = classify_auth_mode(headers)
assert mode is AuthMode.PAYG

Summary

• PAYG mode handles standard API keys (sk-*, x-api-key) and enables aggressive compression.
• OAuth mode processes delegated tokens (sk-ant-oat-*, JWTs) and restricts transformations to lossless operations.
• Subscription mode identifies CLI/IDE clients via User-Agent prefixes and preserves all headers unchanged.
• The classification logic lives in headroom/proxy/auth_mode.py within the classify_auth_mode function (lines 11‑80).
• The system defaults to PAYG when signals are ambiguous, prioritizing operational safety over optimization.

Frequently Asked Questions

What is the default authentication mode in Headroom?

Headroom defaults to PAYG mode when the classifier cannot detect recognizable authentication signals. This safety mechanism ensures that unknown requests are treated as standard API calls that can be safely retried, rather than risking the corruption of subscription client sessions or OAuth token integrity.

How does Headroom distinguish between PAYG and OAuth tokens?

According to the source code in headroom/proxy/auth_mode.py, the classifier examines the Authorization header for specific token prefixes. Standard API keys matching sk-* or sk-ant-api* patterns trigger PAYG mode, while tokens containing sk-ant-oat-* or JWT structures (three Base64-encoded segments separated by periods) trigger OAuth classification.

Why does Headroom treat subscription clients differently?

Subscription clients such as claude-cli or github-copilot often implement strict validation of request headers and user-agent strings. Mutating these headers could trigger security mechanisms that revoke the user's subscription or terminate the session. By classifying these as SUBSCRIPTION mode, Headroom preserves all headers exactly as sent by the client software.

Where is the authentication classification logic implemented?

The core classification logic is implemented in the classify_auth_mode function located in headroom/proxy/auth_mode.py at lines 11 through 80. This file also defines the AuthMode enum and the classify_client helper function. Parity tests validating this logic against the Rust implementation can be found in tests/test_auth_mode.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}