Eliminating Double-Billing: Integrating Claude Subscriptions with the Agent SDK

trates a safe implementation. It includes a validation step to prevent API key shadowing and utilizes the Agent SDK for streaming responses.

import os
import asyncio
from dotenv import load_dotenv
from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.messages import AssistantMessage, TextBlock

load_dotenv()

def ensure_subscription_auth():
    """Validate that API keys are not shadowing the OAuth token."""
    if os.environ.get("ANTHROPIC_API_KEY"):
        raise RuntimeError(
            "Authentication Conflict: ANTHROPIC_API_KEY is detected. "
            "This variable overrides subscription billing. "
            "Please unset this variable to use your Pro/Max quota."
        )
    if not os.environ.get("CLAUDE_CODE_OAUTH_TOKEN"):
        raise RuntimeError(
            "Missing OAuth Token: CLAUDE_CODE_OAUTH_TOKEN is not set. "
            "Run 'claude setup-token' to generate credentials."
        )

async def run_subscription_query(prompt: str) -> str:
    """Execute a query against the subscription quota."""
    ensure_subscription_auth()
    
    full_response = ""
    
    # Stream response tokens
    async for message in query(
        prompt=prompt,
        options=ClaudeAgentOptions(allowed_tools=[])
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    full_response += block.text
                    
    return full_response

async def main():
    try:
        result = await run_subscription_query("Explain the difference between OAuth and API key authentication in one paragraph.")
        print("Response:", result)
    except RuntimeError as e:
        print(f"Configuration Error: {e}")

if __name__ == "__main__":
    asyncio.run(main())

This implementation ensures that your script explicitly checks for authentication conflicts before execution, providing immediate feedback if the environment is misconfigured. The streaming loop captures the response efficiently while billing against your subscription.

Pitfall Guide

1. Silent API Key Shadowing

   • Issue: If ANTHROPIC_API_KEY is present in the environment, the SDK prioritizes it over the OAuth token. This results in API credit consumption without any error message.
   • Fix: Always unset ANTHROPIC_API_KEY in scripts intended for subscription billing. Use the validation function shown in the Core Solution to enforce this.

2. Production Multi-User Deployment

   • Issue: Using OAuth tokens in a production application serving multiple users violates Anthropic's Terms of Service and exposes your subscription to abuse.
   • Fix: Reserve OAuth tokens for personal, local scripts. For production applications, switch to ANTHROPIC_API_KEY and implement proper usage metering.

3. Token Expiration Management

   • Issue: OAuth tokens generated via claude setup-token have a limited lifespan (typically one year). Scripts may fail silently or with authentication errors after expiration.
   • Fix: Implement token rotation procedures or set calendar reminders to regenerate tokens annually. Monitor authentication errors in logs.

4. Environment Variable Pollution

   • Issue: Global environment variables from other projects may leak into your script's context, causing unexpected billing behavior.
   • Fix: Use project-specific .env files and load them explicitly. Avoid exporting credentials in shell profiles unless necessary.

5. Incorrect SDK Selection

   • Issue: Developers may install the standard anthropic package, which does not support OAuth authentication.
   • Fix: Ensure you install claude-agent-sdk (Python) or @anthropic-ai/claude-agent-sdk (TypeScript). Verify the package name in your dependency manager.

6. Rate Limit Violations

   • Issue: Subscription quotas have different rate limits compared to API credits. Aggressive looping in scripts may trigger rate limit errors.
   • Fix: Implement backoff strategies and throttle request rates in your scripts. Monitor for 429 responses and adjust concurrency accordingly.

7. Security Leakage

   • Issue: Committing the OAuth token to version control exposes your subscription to unauthorized access.
   • Fix: Add .env to your .gitignore file. Never hardcode tokens in source files. Use secret management tools for sensitive credentials.

Production Bundle

Action Checklist

• Install @anthropic-ai/claude-code globally via npm.
• Run claude setup-token and copy the generated OAuth token.
• Create a .env file with CLAUDE_CODE_OAUTH_TOKEN.
• Verify ANTHROPIC_API_KEY is unset in the script environment.
• Install claude-agent-sdk in the project dependencies.
• Run a test query to confirm billing against subscription quota.
• Add .env to .gitignore to prevent token leakage.

Decision Matrix

Configuration Template

Create a .env.example file to document required variables:

# Subscription Authentication (Personal Use Only)
# Generate via: claude setup-token
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...

# API Authentication (Production Use)
# Generate via: console.anthropic.com
# ANTHROPIC_API_KEY=sk-ant-api03-...

Quick Start Guide

1. Initialize: Run claude setup-token to generate your OAuth credentials.
2. Configure: Add the token to your .env file as CLAUDE_CODE_OAUTH_TOKEN.
3. Code: Import query from claude_agent_sdk and execute your prompt.
4. Verify: Ensure ANTHROPIC_API_KEY is not set to avoid billing conflicts.
5. Run: Execute your script; requests will now consume your subscription quota.