Headroom GitHub Copilot CLI Wrap Mode Authentication: 3 Methods Explained

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, 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, 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.

# 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, the resolve_provider_type function determines whether to use Anthropic or OpenAI based on the effective backend configuration:

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) 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:

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:

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, 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.

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