Use a Claude Subscription Instead of an API Key? Cost and Limits

For one person doing heavy agent work most days, a Claude or ChatGPT subscription is usually cheaper than an API key, as long as its five-hour and weekly limits fit how you work. An API key is the right call for products other people use, CI and shared automation, occasional work, or any deadline where waiting for a limit to reset costs more than the tokens. As of September 15, 2026, a Claude plan can stand in for a key inside Claude Code, and a ChatGPT plan inside Codex. Google's consumer plans no longer work in Gemini CLI, so there a key is the only option.

This page is about cost and limits: what each costs, how the limits behave, how to switch a CLI from one to the other, and the errors you'll meet. Whether another app may use your plan at all is a separate question, covered in using your Claude or ChatGPT subscription in other apps.

What is the difference between a subscription and an API key?#

A subscription is a flat monthly price with usage limits that reset on a clock. An API key is metered: every token is billed, and there is no ceiling unless you set one. They are not two prices for one product. They are two products under two agreements. Anthropic's Consumer Terms cover Pro and Max, and its Commercial Terms cover API keys. OpenAI splits the same way between its Terms of Use and its Business Terms.

A subscription is cheaper for heavy personal use and has hard edges. An API key is unambiguous everywhere and can surprise you with a bill.

What does agent work cost on a subscription vs an API key?#

Agents use far more tokens than chat, because every step re-sends the conversation plus whatever the tools returned. Anthropic's cost guide says each Claude Code turn carries file contents, tool calls and multi-step reasoning, "so one debugging session can consume more than a day of chat."

Here is an illustration using Anthropic's published API prices as of September 2026. The day's token volume is a made-up but plausible heavy day of agent work, not a measurement:

• 3 million input tokens, 90% of them cache reads, plus 150,000 output tokens
• Claude Sonnet 5 ($2 input, $0.20 cache read, $10 output per million): about $0.60 + $0.54 + $1.50 = $2.64 a day
• Claude Opus 5 ($5 input, $0.50 cache read, $25 output per million): about $1.50 + $1.35 + $3.75 = $6.60 a day

This leaves out the cache-write premium (1.25× input for five-minute caching), so real numbers run a little higher. Over 20 working days that is roughly $53 a month on Sonnet 5 and $132 on Opus 5. Claude Pro is $20 a month ($17 billed annually), and Max starts at $100.

What the arithmetic says:

• One person, most days: a plan is usually cheaper, as long as the limits fit how you work.
• Bursty or occasional work: a key can be cheaper, because you pay nothing on quiet days.
• Shared automation, CI, or a product other people use: a key, regardless of price. A personal plan cannot be shared.
• You keep hitting the plan limit on real deadlines: extra usage or a key, because waiting for a reset costs more than the tokens.

How do subscription usage limits work?#

• Claude. Plan limits reset on rolling five-hour windows, with a weekly limit on top. Anthropic's help center says Pro and Max limits "are shared across Claude and Claude Code, meaning all activity in both tools counts against the same usage limits." On Team and seat-based Enterprise plans, Anthropic's cost guide says each member's Claude Code usage draws from a per-seat allowance that "resets on a rolling five-hour window and a weekly window" and is shared with Claude chat and Cowork.
• Claude extra usage. When you hit your limit, Pro and Max plans can turn on usage credits. Anthropic's help center says they are "charged separately from your paid Claude subscription", priced at standard API rates, and "apply to both Claude conversations and Claude Code terminal usage."
• ChatGPT. OpenAI's Codex pricing docs say "Local messages and cloud chats share your plan's usage allowance", measured in five-hour windows with a weekly allowance that depends on the plan and model. Plus and Pro can buy more credits when it runs out.
• Gemini. Antigravity CLI on Google AI Pro or Ultra gets a quota that refreshes every five hours, per Google's plans page, which also says bring-your-own-key is not supported for extra limits. Gemini Code Assist Standard and Enterprise are listed with daily quotas.

How to watch it:

• Claude Code: run /usage. On a Pro, Max, Team or Enterprise plan it shows plan usage bars and a breakdown of what used them. The dollar figure in its Session block is an estimate at list price, and Anthropic says it "isn't relevant for billing purposes" on a Pro or Max plan. On claude.ai, Settings → Usage shows your session and weekly limits.
• Codex: run /status in a CLI session, or open the usage dashboard at chatgpt.com/codex/settings/usage.

Can you use a Claude Pro or Max subscription instead of an API key?#

Inside Claude Code, yes. Anthropic's authentication docs list a Claude Pro or Max subscription, and a Team or Enterprise seat, as normal ways to log in. The first run of claude opens a browser, you sign in, and turns draw from your plan's limits.

claude setup-token and CLAUDE_CODE_OAUTH_TOKEN#

For scripts, CI or any machine without a browser, run:

claude setup-token

It opens the same authorization flow as /login and prints a one-year OAuth token. It does not save the token anywhere. You set it yourself:

export CLAUDE_CODE_OAUTH_TOKEN=your-token

Per Anthropic's docs, the token "authenticates with your Claude subscription and requires a Pro, Max, Team, or Enterprise plan". It can only make model requests, and bare mode (--bare) does not read it.

Which credential Claude Code actually bills#

Watch the precedence. Claude Code tries a cloud provider, then ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, CLAUDE_CODE_OAUTH_TOKEN, then Anthropic profile credentials, and last your /login subscription. A forgotten ANTHROPIC_API_KEY moves you onto metered billing while your plan sits idle: interactive mode asks once and remembers your answer, and claude -p uses the key without asking. /status shows which credential is live.

Interactive Claude Code, claude -p and the Agent SDK on your own projects draw from your plan. Third-party harnesses are another matter: since April 4, 2026 Anthropic has billed tools like OpenClaw as extra usage, while its June notice says Agent SDK apps still draw plan limits. The full rules and the timeline are in using your subscription in other apps.

Can you use Codex with ChatGPT Plus instead of an API key?#

Yes. OpenAI's help center covers using Codex with a ChatGPT plan, with limits that vary by plan. Run codex login and pick Sign in with ChatGPT. A browser opens and the credentials come back to the CLI.

OpenAI's Codex auth docs spell out what API-key mode changes:

• Usage bills "at standard API rates" instead of drawing on plan limits.
• Codex cloud requires a ChatGPT sign-in, so it is unavailable with a key.
• "Some features that rely on ChatGPT workspace access or cloud services are limited or unavailable."
• OpenAI recommends API keys "for programmatic Codex CLI workflows, such as CI/CD jobs." In managed environments, admins can provision Codex access tokens for automation instead.

What changed for Gemini on June 18, 2026?#

Google announced on May 19 that "on June 18, 2026, Gemini CLI and Gemini Code Assist IDE extensions will stop serving requests for Google AI Pro and Ultra, as well as those using it free of charge." On the day, the Gemini CLI team confirmed it and pointed individuals to Antigravity CLI.

Google's deprecation page says the "Login with Google" option is no longer available for those consumer tiers. On v0.54.0 the failure can be silent: the CLI drops you back on the API key screen with no explanation.

What still works, per Google's deprecation page and blog post:

• Gemini CLI with a paid Gemini API key, or a Gemini Enterprise Agent Platform (Vertex) key. This is metered.
• Gemini Code Assist Standard or Enterprise licenses. They are unaffected.
• Antigravity CLI and Antigravity 2.0 with a Google AI Pro or Ultra plan. Google's plans page gives those plans a quota that refreshes every five hours.

So for Gemini in any terminal tool other than Antigravity, the subscription-or-key question has one answer: a key.

What about Grok and open models?#

Grok. xAI launched Grok Build on May 25, 2026 for SuperGrok and X Premium Plus subscribers. grok login signs in through xAI's OAuth, and per the auth docs, XAI_API_KEY is the fallback when no session token is active.

Open models. A model running on your own machine, for example through Ollama, costs nothing per token and has no terms about logins. Hosted open models through OpenRouter, Together, Fireworks or Groq are API keys by another name, and they are metered.

When is an API key the right answer?#

A subscription is priced for one person working. Use an API key when any of these are true:

• You are building a product for other people. Anthropic's legal page says developers building products "should use API key authentication". Each of your users brings their own credential.
• You run CI/CD or shared automation. OpenAI says to "Use API key authentication for programmatic Codex CLI workflows, such as CI/CD jobs." Even OpenClaw's Anthropic docs say "For shared production automation, use an Anthropic API key instead of Claude CLI."
• A team shares the spend. Anthropic: "You may not share your Account login information, Anthropic API key, or Account credentials with anyone else." OpenAI: "You may not share your account credentials or make your account available to anyone else." Use a seat per person, or an organisation API key.
• You need predictable cost. Per-token billing has no five-hour windows or weekly resets. You can set spend limits and read exact numbers in the provider's console.
• Your only plan is Google AI Pro and you want Gemini outside Antigravity.
• You have hit the plan's ceiling on real work, and waiting for a reset costs more than the tokens would.

Common errors, and what they mean#

"OAuth token does not meet scope requirement"#

The full message looks like API Error: 403 OAuth token does not meet scope requirement any_of(org:service_key_inference, user:ccr_inference, user:developer, user:inference, …). The token can identify you but cannot run the model, because it was granted without user:inference.

OAuth servers may grant fewer scopes than a client asks for, without an error. We saw this on September 2, 2026: a browser sign-in that requested several scopes came back with only user:file_upload user:profile. Signing in the same way again gives the same broken token. Mint one with claude setup-token, which requests only user:inference, and remove the old token from your environment.

401 "OAuth access token is invalid"#

This one has three usual causes:

• A token copied with something extra. setup-token prints the token and then a line of prose. We have seen a stored token with "Store this token securely" glued to the end.
• A revoked or expired token. A setup-token lasts a year.
• A disabled API key outranking your login. An ANTHROPIC_API_KEY from a disabled organisation takes precedence. unset it and check /status.

An expired /login session reports Login expired · Please run /login instead.

Rate limits that look like answers#

Claude Code writes some API errors into the transcript as the assistant's reply and ends the turn as a success. "You're out of usage credits" or "Failed to authenticate" can arrive as reply text on a turn that reports success, so a script that only checks for an error records a limit as a finished job. Check the reply text too.

For Codex, the look-alike failure is an MCP tool refused under approval_policy = "never". We cover it in Fixing "MCP tool call requires approval".

How Universe runs on the logins you already have#

Universe is a Mac app where agents do real work: files, a signed-in Chrome, your connected apps. It runs those agents through the model account you already pay for, so the subscription-or-key choice above stays yours. It charges for the workspace software, not for model usage. There are no credits, and it never resells tokens (pricing).

• Claude Code. A copy of Claude Code ships inside the app. Your Claude Pro or Max plan pays, or an Anthropic API key. Sign in with Claude runs Claude Code's own claude setup-token flow, so the sign-in completes on Anthropic's pages.
• Codex. A copy of Codex ships inside the app too. It runs on your ChatGPT Plus, Pro or Business login, or an OpenAI API key.
• Gemini. Gemini CLI runs on your Google account or a Gemini API key. Given Google's June change, for most individuals that means a key.
• Grok. Your xAI key.
• Open models. Through Mantis, pointed at a local Ollama or a self-hosted model. Local models are free. Hosted providers need your own key and are not.

What it does with those accounts that matters for cost:

• A plan first, a key second. Add several accounts in order. When the first is rate-limited, the next runs, and the transcript says so. So a subscription can do most of the work and a key can pick up the rest on a deadline.
• Every answer records which account paid and what it cost, shown on hover. For a subscription turn that figure is the CLI's estimate, not a charge. Your plan's limits still apply in full.
• A sign-in that returns a token unable to run the model is refused rather than stored: the scope error above, caught at the door.
• A workspace can share a login with its team, with an optional per-member monthly cap, and a space can pay for the turns inside it. Codex and Gemini can only pool an API key. For Claude, a personal Pro or Max login is not yours to share, so put a company API key in the shared slot.

Where it does not fit: Universe is Mac only. If all you want is Claude Code in a terminal, you do not need anything besides Claude Code. And if your only plan is Google AI Pro, Google's Antigravity is the tool that plan pays for.

Related: using your Claude or ChatGPT subscription in other apps, running Claude Code, Codex, Gemini and Grok from one app, and OpenClaw alternatives after the Claude subscription ban. Or download Universe for Mac.

What changed for cost in 2026#

Newest first. The full policy timeline is in the rules post.

• 2026-09-15. Page checked. Anthropic's Agent SDK credit is still paused with no new date.
• 2026-06-18. Gemini CLI stops serving Google AI Pro, Ultra and free individual accounts. For Gemini CLI, that leaves a key or a Code Assist licence.
• 2026-06-15. Anthropic pauses the planned Agent SDK credit ($20 for Pro, $100 for Max 5x, $200 for Max 20x). Agent SDK, claude -p and third-party app usage keep drawing from plan limits.
• 2026-04-04. Anthropic stops Claude plan limits covering third-party harnesses such as OpenClaw. Those harnesses bill extra usage, or you use an API key.