# Headroom GitHub Copilot CLI Wrap Mode Authentication: 3 Methods Explained

> Discover Headroom's GitHub Copilot CLI wrap mode authentication: OAuth, business subscription tokens, and BYOK API keys. Secure your AI coding assistant today.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-06

---

**Headroom supports OAuth tokens from system keychains, business subscription tokens with endpoint rewriting, and BYOK provider API keys for Anthropic or OpenAI backends when wrapping the GitHub Copilot CLI.**

Headroom is an open-source proxy that intercepts and routes GitHub Copilot CLI requests through configurable backends. When running in wrap mode, the tool authenticates with multiple services: GitHub's Copilot APIs for user sessions, business endpoints for enterprise subscriptions, and third-party LLM providers when using bring-your-own-key (BYOK) configurations. Understanding these authentication pathways is essential for securely deploying Headroom in enterprise environments.

## OAuth Token Authentication

The **Copilot OAuth token** (subscription token) represents the primary authentication method. This token grants access to GitHub's Copilot API on behalf of the user.

### Token Discovery Sources

Headroom discovers OAuth tokens through a cascading priority system implemented in the authentication module. According to [`tests/test_copilot_subscription_smoke.py`](https://github.com/chopratejas/headroom/blob/main/tests/test_copilot_subscription_smoke.py), the resolver first attempts platform-specific secure storage:

- **macOS Keychain**: Reads from `copilot_macos_keychain`
- **Linux Secret Service**: Retrieves from `copilot_linux_secret`
- **Copilot CLI Config**: Parses `~/.copilot/config.json`

If these dedicated sources fail, Headroom falls back to generic GitHub environment variables, including `GITHUB_TOKEN`, `GITHUB_COPILOT_GITHUB_TOKEN`, and `COPILOT_GITHUB_TOKEN`.

### Applying Authentication Headers

Once discovered, the token is attached to every proxied request. As shown in [`tests/test_proxy_copilot_auth_hooks.py`](https://github.com/chopratejas/headroom/blob/main/tests/test_proxy_copilot_auth_hooks.py), the `apply_copilot_api_auth` function injects an `Authorization: Bearer <token>` header before forwarding requests to `https://api.githubcopilot.com/models` or the resolved business endpoint.

```python

# Internal flow: OAuth token application

monkeypatch.setattr(openai_mod, "apply_copilot_api_auth", fake_apply)

# Result: Authorization: Bearer gho-real-copilot

```

## Business Subscription Authentication

Enterprise users with business-level Copilot subscriptions utilize a separate authentication flow that rewrites API endpoints. When `resolve_subscription_bearer_token` returns a valid token, Headroom calls the Copilot user-info endpoint (`/user`) via `_fetch_copilot_user_info` to discover organization-specific API URLs.

The `resolve_copilot_api_url` function then rewrites the upstream URL from the default `api.githubcopilot.com` to the business endpoint, typically `https://api.business.githubcopilot.com/...`. This ensures all API calls route through the organization's dedicated infrastructure while maintaining the same OAuth token authentication.

## BYOK Provider API Keys

When using a proxy backend other than the default `"auto"` mode, Headroom requires **bring-your-own-key (BYOK)** authentication for the underlying LLM provider.

### Provider Type Resolution

In [`headroom/providers/copilot/wrap.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/copilot/wrap.py), the `resolve_provider_type` function determines whether to use Anthropic or OpenAI based on the effective backend configuration:

```python
def resolve_provider_type(...):
    return "anthropic" if effective_backend == "anthropic" else "openai"

def provider_key_source(provider_type: str) -> str:
    return "ANTHROPIC_API_KEY" if provider_type == "anthropic" else "OPENAI_API_KEY"

```

### Environment Variable Injection

The `build_launch_env` function (also in [`wrap.py`](https://github.com/chopratejas/headroom/blob/main/wrap.py)) prepares the launch environment for the Copilot CLI wrapper. If `COPILOT_PROVIDER_API_KEY` is not already present, Headroom copies the appropriate API key from `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` into the launch environment.

This injection allows the proxy to authenticate with the chosen provider while the Copilot CLI believes it is communicating with GitHub's native API.

## How Authentication Flows in Wrap Mode

The complete wrap mode authentication sequence involves coordination between the proxy detector and credential builders:

1. **Detect the running proxy**: `detect_running_proxy_backend` reads the `/health` endpoint to identify whether Anthropic or OpenAI is active.

2. **Choose provider type**: `resolve_provider_type` selects `"anthropic"` for Anthropic backends, otherwise defaults to `"openai"`.

3. **Gather credentials**: `build_launch_env` injects:
   - `COPILOT_PROVIDER_TYPE` (anthropic/openai)
   - `COPILOT_PROVIDER_BASE_URL` (the proxy address)
   - `COPILOT_PROVIDER_WIRE_API` (defaults to "completions")
   - `COPILOT_PROVIDER_API_KEY` (sourced from provider-specific env vars if missing)

4. **Apply the OAuth token**: Before forwarding requests, `apply_copilot_api_auth` adds the GitHub Copilot bearer token sourced from keychains, secret stores, or fallback environment variables.

5. **Handle business subscriptions**: If the OAuth token resolves to a business endpoint (detected via user info API), the proxy rewrites all upstream URLs to the organization-specific address.

## Configuration Examples

To authenticate with OpenAI in BYOK mode while maintaining Copilot OAuth for the CLI:

```bash
export HEADROOM_BACKEND="openai"
export OPENAI_API_KEY="sk-..."

# Headroom automatically injects this as COPILANT_PROVIDER_API_KEY

headroom wrap -- copilot suggest "hello world"

```

For business subscription authentication, set the standard Copilot token and let Headroom auto-discover the business endpoint:

```bash
export COPILOT_GITHUB_TOKEN="gho_..."

# Headroom resolves api.business.githubcopilot.com automatically

headroom wrap -- copilot explain "def hello():"

```

## Summary

- **OAuth Token Authentication**: Sources tokens from macOS Keychain, Linux Secret Service, `~/.copilot/config.json`, or fallback environment variables (`GITHUB_TOKEN`, `COPILOT_GITHUB_TOKEN`), applying them via `apply_copilot_api_auth`.

- **Business Subscription Support**: Discovers organization-specific endpoints through `/user` API calls and rewrites upstream URLs to `api.business.githubcopilot.com` using `resolve_copilot_api_url`.

- **BYOK Provider Keys**: Resolves Anthropic or OpenAI backends via `resolve_provider_type` in [`wrap.py`](https://github.com/chopratejas/headroom/blob/main/wrap.py), injecting `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` as `COPILOT_PROVIDER_API_KEY` for direct LLM provider authentication.

## Frequently Asked Questions

### How does Headroom prioritize multiple available authentication sources?

Headroom checks platform-specific secure storage first (macOS Keychain or Linux Secret Service), then falls back to the Copilot CLI configuration file at `~/.copilot/config.json`. Only if these sources fail does it check generic GitHub environment variables like `GITHUB_TOKEN` or `COPILOT_GITHUB_TOKEN`, ensuring the most secure storage method takes precedence.

### Can I use a personal Copilot subscription alongside BYOK provider keys?

Yes. Headroom differentiates between GitHub Copilot authentication (OAuth token) and LLM provider authentication (API keys). You can use a personal Copilot OAuth token for CLI session management while routing actual completions through your own Anthropic or OpenAI API keys configured via `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.

### What happens when a business subscription token is detected?

When Headroom detects a business token, it calls the Copilot user-info endpoint to retrieve the organization-specific API base URL. The `resolve_copilot_api_url` function then rewrites all proxied requests from `api.githubcopilot.com` to the business endpoint (e.g., `api.business.githubcopilot.com`), ensuring compliance with enterprise routing requirements while maintaining the same OAuth bearer authentication headers.

### Is it safe to store provider API keys in environment variables?

While Headroom supports reading `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` from environment variables for BYOK mode, these are injected into the wrapped process environment via `build_launch_env`. For production deployments, consider using secret management tools that populate these variables temporarily, as the keys reside in process memory during the Copilot CLI session.