Prefer ANTHROPIC_API_KEY over OAuth token when both are set (#62)

* fix(gateway): prefer API key over OAuth token when both are set

Reverses the auth precedence so ANTHROPIC_API_KEY takes priority over
CLAUDE_CODE_OAUTH_TOKEN. This aligns with documentation guidance that
API keys are recommended for automation, while OAuth tokens are
appropriate for personal testing and development only.

Fixes #61

* docs: hide OAuth token option from public documentation

Remove CLAUDE_CODE_OAUTH_TOKEN from user-facing docs and examples.
The option remains functional but is now undocumented, discoverable
only by developers reading the source code.

Inline code comments now include terms of use warning explaining that
OAuth tokens may violate Anthropic's Consumer Terms for automated use.

Author: matthew-petty

.env.example

@@ -5,12 +5,8 @@
 # Generate a secure key with: openssl rand -hex 32
 CLAUDE_CODE_GATEWAY_API_KEY=your-secret-api-key
 
-# Claude authentication (one of these is required)
-# Recommended: Anthropic API key for automation
+# Claude authentication (required)
 ANTHROPIC_API_KEY=
 
-# Alternative: OAuth token (Claude Pro/Max) - for personal testing and development only
-# CLAUDE_CODE_OAUTH_TOKEN=
-
 # Gateway server port (optional, default: 3100)
 GATEWAY_PORT=3100

README.md

@@ -101,10 +101,9 @@ console.log(result.text);
 >
 > - **Use Docker**: containers provide essential filesystem and process isolation
 > - **Internal networks only**: deploy on VPN or Docker networks, not public internet
-> - **Use API keys for automation**: Anthropic API keys are the recommended authentication method. They operate under the [Commercial Terms](https://www.anthropic.com/legal/commercial-terms) which permit programmatic access.
-> - **OAuth tokens for personal use only**: Claude Pro/Max OAuth tokens are appropriate for personal testing and development. For production or shared deployments, use an API key.
+> - **Use API keys**: Anthropic API keys operate under the [Commercial Terms](https://www.anthropic.com/legal/commercial-terms) which permit programmatic access
 >
-> See [Environment Variables](docs/environment-variables.md#terms-considerations) for details.
+> See [Environment Variables](docs/environment-variables.md) for configuration details.
 
 ## Documentation
 

docker-compose.yml

@@ -14,8 +14,7 @@ services:
       HOME: /home/bun
       # Authentication for the gateway API
       CLAUDE_CODE_GATEWAY_API_KEY: ${CLAUDE_CODE_GATEWAY_API_KEY:-}
-      # Claude auth: ANTHROPIC_API_KEY recommended for automation (see docs/environment-variables.md)
-      # OAuth tokens are appropriate for personal testing and development only
+      # Claude authentication
       ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
       CLAUDE_CODE_OAUTH_TOKEN: ${CLAUDE_CODE_OAUTH_TOKEN:-}
     volumes:

docs/environment-variables.md

@@ -5,13 +5,7 @@
 | Variable | Description |
 |----------|-------------|
 | `CLAUDE_CODE_GATEWAY_API_KEY` | Bearer token for gateway API requests |
-
-## Claude Authentication (one required)
-
-| Variable | Description |
-|----------|-------------|
-| `ANTHROPIC_API_KEY` | Anthropic API key (recommended for automation) |
-| `CLAUDE_CODE_OAUTH_TOKEN` | OAuth token (Claude Pro/Max). See [Terms Considerations](#terms-considerations). |
+| `ANTHROPIC_API_KEY` | Anthropic API key for Claude authentication |
 
 ## Optional
 
@@ -28,10 +22,6 @@ ANTHROPIC_API_KEY=sk-ant-...
 GATEWAY_PORT=3100
 ```
 
-## Terms Considerations
-
-**API keys** are the recommended authentication method for Koine and automation use cases. They operate under [Anthropic's Commercial Terms](https://www.anthropic.com/legal/commercial-terms) which explicitly permit programmatic access.
-
-**OAuth tokens** (Claude Pro/Max subscriptions) are appropriate for personal testing and development only. For production or shared deployments, use an API key.
+## Terms
 
-If both are set, the OAuth token takes precedence. For automation, set only `ANTHROPIC_API_KEY`.
+Anthropic API keys operate under [Anthropic's Commercial Terms](https://www.anthropic.com/legal/commercial-terms) which explicitly permit programmatic access.

packages/gateway/__tests__/cli.test.ts

@@ -44,23 +44,23 @@ describe("CLI Module", () => {
 			process.env = originalEnv;
 		});
 
-		it("returns process.env when no OAuth token is set", () => {
-			process.env.CLAUDE_CODE_OAUTH_TOKEN = undefined;
-			process.env.ANTHROPIC_API_KEY = "test-api-key";
+		it("returns process.env when no API key is set", () => {
+			process.env.ANTHROPIC_API_KEY = undefined;
+			process.env.CLAUDE_CODE_OAUTH_TOKEN = "oauth-token";
 
 			const env = buildClaudeEnv();
 
-			expect(env.ANTHROPIC_API_KEY).toBe("test-api-key");
+			expect(env.CLAUDE_CODE_OAUTH_TOKEN).toBe("oauth-token");
 		});
 
-		it("clears ANTHROPIC_API_KEY when OAuth token is present", () => {
-			process.env.CLAUDE_CODE_OAUTH_TOKEN = "oauth-token";
+		it("clears OAuth token when API key is present", () => {
 			process.env.ANTHROPIC_API_KEY = "test-api-key";
+			process.env.CLAUDE_CODE_OAUTH_TOKEN = "oauth-token";
 
 			const env = buildClaudeEnv();
 
-			expect(env.ANTHROPIC_API_KEY).toBeUndefined();
-			expect(env.CLAUDE_CODE_OAUTH_TOKEN).toBe("oauth-token");
+			expect(env.CLAUDE_CODE_OAUTH_TOKEN).toBeUndefined();
+			expect(env.ANTHROPIC_API_KEY).toBe("test-api-key");
 		});
 	});
 

packages/gateway/src/cli.ts

@@ -5,7 +5,12 @@ import type { ClaudeCliOutput, ErrorCode, UsageInfo } from "./types.js";
 
 /**
  * Builds environment variables for Claude CLI with auth precedence.
- * Prefers OAuth token (Max subscription) over API key when both are present.
+ * Prefers API key over OAuth token when both are present.
+ *
+ * CLAUDE_CODE_OAUTH_TOKEN is an undocumented fallback for personal testing only.
+ * OAuth tokens (Claude Pro/Max) operate under Anthropic's Consumer Terms which
+ * prohibit automated access. Use ANTHROPIC_API_KEY for all automation.
+ * See: https://www.anthropic.com/legal/consumer-terms
  *
  * Also passes through tool proxy variables for Claude skills that need to
  * invoke Inbox Zero API tools.
@@ -15,9 +20,10 @@ export function buildClaudeEnv(options?: {
 }): NodeJS.ProcessEnv {
 	const env = { ...process.env };
 
-	// Prefer OAuth token for Max subscribers over API key
-	if (env.CLAUDE_CODE_OAUTH_TOKEN) {
-		env.ANTHROPIC_API_KEY = undefined;
+	// API key takes precedence - OAuth is undocumented fallback for personal testing only.
+	// OAuth tokens may violate Anthropic's Consumer Terms for automated use.
+	if (env.ANTHROPIC_API_KEY) {
+		env.CLAUDE_CODE_OAUTH_TOKEN = undefined;
 	}
 
 	// Pass through tool proxy variables for Claude skills