Subscription Auth

Use your Claude Pro / Qwen CLI subscription instead of an API key

Use the subscription you already pay for — Claude Pro, Qwen CLI, etc. — to power your Agent without a separate API key.

from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    instructions="You are helpful.",
    llm="claude-haiku-4-5",
    auth="claude-code",
)
agent.start("Hello")

The user chats via the agent; subscription auth supplies credentials instead of a raw API key.

Quick Start

1. Login to CLI

   claude /login (Claude Pro) — or qwen login

2. Use in Agent

   from praisonaiagents import Agent
   
   agent = Agent(
       name="assistant",
       instructions="You are helpful.",
       llm="claude-haiku-4-5",
       auth="claude-code",
   )
   agent.start("Hello")

How It Works

Subscription Auth enables agents to use your existing subscriptions without requiring separate API keys.

Cloning & multi-channel

clone_for_channel() forwards auth=, so gateway and multi-channel setups that duplicate the agent per channel keep subscription billing.

from praisonaiagents import Agent

agent = Agent(name="t", llm="anthropic/claude-sonnet-4-5", auth="claude-code")
clone = agent.clone_for_channel()
# clone.auth == "claude-code"

Supported Providers

Which subscription auth provider should you use?

Common Patterns

No model needed

Skip llm= and the provider’s vendor model is chosen for you.

from praisonaiagents import Agent

# No llm= — defaults to anthropic/claude-sonnet-4-5 for claude-code,
# openai/qwen3-coder-plus for qwen-cli.
agent = Agent(name="t", auth="claude-code")
agent.start("Hello")

Choose your refresh path

When a claude-code token expires, pick the action that matches your setup — PraisonAI never rotates it for you.

Telegram bot using your Claude subscription

from praisonaiagents import Agent
from praisonai.bots import Bot

agent = Agent(
    name="claude-bot",
    instructions="You are a helpful Telegram bot.",
    llm="claude-haiku-4-5",
    auth="claude-code",
)

bot = Bot("telegram", agent=agent)
bot.run()

Switching between API key and subscription

from praisonaiagents import Agent

# Use your Claude Pro subscription
agent_subscription = Agent(
    name="claude-subscription",
    llm="claude-haiku-4-5",
    auth="claude-code",  # Uses your subscription
)

# Use API key (traditional method — set ANTHROPIC_API_KEY)
agent_api_key = Agent(
    name="claude-api",
    llm="claude-haiku-4-5",
)

# Both work identically
response1 = agent_subscription.start("Hello")
response2 = agent_api_key.start("Hello")

Custom provider (advanced)

from praisonaiagents.auth import register_subscription_provider, SubscriptionCredentials

class MyAuth:
    def resolve_credentials(self) -> SubscriptionCredentials:
        return SubscriptionCredentials(
            api_key="my-token",
            base_url="https://my-provider.com/v1",
            headers={"x-custom": "value"},
        )

    def refresh(self) -> SubscriptionCredentials:
        return self.resolve_credentials()

    def headers_for(self, base_url: str, model: str) -> dict:
        return {"user-agent": "my-provider/1.0.0"}

register_subscription_provider("mine", lambda: MyAuth())

Configuration Options

Best Practices

Troubleshooting

“No Claude Code credentials found”

Solution: Install Claude Code CLI and run claude /login to authenticate with your Claude Pro account.

# Install Claude Code (if not already installed)
# Then login with your Claude Pro account
claude /login

invalid_request_error on a Claude Code request

What it means: This is a genuine client-side error (a malformed request), not a retryable auth failure. PraisonAI no longer misclassifies it as an expired-token error, so it surfaces directly instead of being silently retried.

Solution: Check the request itself — model name, message shape, or parameters. If you also see auth failures, re-authenticate the shared session:

claude /login

macOS Keychain prompt every run

Solution: Grant security command access to avoid repeated prompts. This is handled automatically by the system after first access.

Anthropic 500 errors

Issue: OAuth tokens require specific headers that are automatically included.

What PraisonAI does: Automatically sends required headers:

• user-agent: claude-cli/<version> (external, cli)
• x-app: cli
• anthropic-beta: interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14,claude-code-20250219

Codex / Gemini raise AuthError

Expected behavior: These providers are experimental and not yet usable. They raise AuthError at construction time — Agent(auth="codex") raises immediately, not at first request.

from praisonaiagents import Agent

Agent(name="t", auth="codex")
# AuthError: Codex provider is experimental — needs Responses API transport wiring

AuthError: Unknown subscription provider

Cause: A typo or unregistered id in auth=. Valid ids are claude-code, codex, gemini-cli, and qwen-cli. The typo now surfaces at construction rather than silently billing your API key.

from praisonaiagents import Agent
from praisonaiagents.auth.subscription.protocols import AuthError

try:
    Agent(name="t", llm="gpt-4o-mini", auth="nonexistent-provider")
except AuthError as e:
    print(e)
# Unknown subscription provider 'nonexistent-provider'.
# Registered: ['claude-code', 'codex', 'gemini-cli', 'qwen-cli']

I passed a bare model name and it silently billed my API key

Cause: Before PR #4147, auth= was dropped when llm= was a bare model name (or omitted), so requests went out on OPENAI_API_KEY. This is fixed — upgrade praisonai-agents to a version that includes the fix and every llm= shape honours auth=.

Mixing an OpenAI model with subscription auth

Behavior: Responses-API-eligible models (gpt-4o, o1, o3, openai/) with subscription auth now route to the subscription’s vendor. The simpler path is to omit llm= and let the auto-default pick the right vendor for your seat.

Token Detection Priority (Claude Pro)

Tokens are resolved in this exact order:

1. ANTHROPIC_TOKEN environment variable
2. CLAUDE_CODE_OAUTH_TOKEN environment variable
3. macOS Keychain (Claude Code-credentials)
4. ~/.claude/.credentials.json file

Environment Variable Override

You can disable subscription auth entirely (planned):

export PRAISONAI_DISABLE_SUBSCRIPTION_AUTH=1

Related