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

> Explore Headroom's authentication modes for LLM providers: PAYG, OAuth, and Subscription. Secure your API requests and optimize compression policies effectively.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: api-reference
- Published: 2026-06-13

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.

```python
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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/tests/test_auth_mode.py).