API key billing

A Claude Code session runs on your Claude subscription or on your own Anthropic API key. You choose the credential for each session when you create it, and you can switch a running session from one to the other. A session on a key is billed to the key's owner at Anthropic's API rates; a session on a subscription draws on that subscription, as before.

Add your key

1. Open Settings → Keys.
2. In API Keys, choose the provider anthropic, paste the key, and optionally give it a label.
3. Select Add key.

The key is stored on this machine only and is shown masked after you add it. Hapimatic never puts the key in a Claude Code session's environment: Claude Code asks Hapimatic for it when it needs it. An OpenCode session that uses the anthropic provider is different: it receives the same stored key in its configuration. Adding another Anthropic key replaces the one you have.

The key must be workspace-scoped. Create it inside a workspace in the Claude Console. An organization-level key is refused on every request with "not scoped to a workspace", so a session started on one cannot run.

Start a session on your key

1. On the new-session page, choose Claude Code and open the Provider Account field.
2. Pick your key in the API keys group.

The launcher then switches to SDK and locks there, with the note "Required for API billing": a session on a key runs on the SDK launcher only. Picking an account instead clears the key.

Switch a running session

Open the session's Session Configuration, pick a key or an account in the Account row, and select Apply changes. The session restarts and continues the same conversation after a short pause. For a disconnected session the button reads Save changes: nothing restarts, and the new credential applies when the session reconnects. Turns that ran before the switch keep the credential they ran under; only the turns after it use the new one.

The key group is not available, and says why, when the session:

• runs on the pty or tmux launcher, or has no recorded launcher: start a new session on the key instead;
• belongs to another machine: a key never leaves the machine that stores it;
• is in local mode: return it to remote mode first.

What the two figures mean

The session's usage widget can show two dollar figures:

• API cost (mint): what the key turns cost at Anthropic's API rates. This is real spend, billed to the key's owner.
• API value with an EQ. marker (blue): what the subscription turns would have cost at API rates. Nothing is charged for it; your subscription covers those turns.

A session that switched shows both figures side by side. Switching resets neither figure and recolors no earlier turn. Each turn's cost footer takes the color of the credential that turn ran under.

Prompt caching

Claude Code caches the conversation on every request, whichever credential the session uses, so there is nothing to turn on. The "prompt caching" link in the Claude Console is developer documentation for apps that call the API directly.

On a key, Claude Code keeps cache entries for 5 minutes by default. After a longer pause, such as waiting for your reply or a long test run, the next turn would write the whole conversation into the cache again. Hapimatic sets a 1-hour cache for key sessions instead, so a pause of up to an hour reads the cached conversation. A 1-hour cache write costs 2× the input rate instead of 1.25×, and every write is charged at that rate: the new part of each turn, and the whole conversation again after a pause of more than an hour. A session that often pauses for 5 to 60 minutes pays far less than it would by rewriting the whole conversation after each pause. A session that seldom pauses that long, or that usually sits idle for more than an hour between turns, pays more. Subagents and Claude Code's background requests keep the 5-minute cache. Subscription sessions are unchanged: within its usage limits, a subscription already gets a 1-hour cache from Claude Code.

If your key sessions seldom pause for 5 to 60 minutes, you can return them to the 5-minute cache: add "CLAUDE_CODE_PROMPT_CACHE_TTL": "5m" to the env block of ~/.claude/settings.json on the machine that runs the sessions. This applies to every Claude Code session on that machine, subscription sessions included.

Limits

• Claude Code only. Codex, Gemini CLI and OpenCode sign in their own way; see Supported agent CLIs.
• SDK launcher only. The pty and tmux launchers refuse a key.
• This machine only. A session that runs on another machine cannot use a key stored here.
• Not for scheduled tasks. A scheduled task cannot be set to run on a key.
• No automatic moves. Nothing moves a running session onto or off a key by itself: account selection, the rate-limit account switch and token refresh all leave a key session alone. Only your switch does.
• Hapimatic keeps ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN out of subscription sessions. Claude Code ranks both above a subscription sign-in, so a session that inherited one would bill it instead of your subscription. Hapimatic removes both from every Claude Code session that is not on a key, on every launcher. To run a session on a key, add the key under Settings → Keys.
• Removing a key does not stop a running session. Claude Code keeps using the key it already has until a request is rejected, so a session that is running when you remove or replace its key keeps billing that key. To stop spending now, stop the session, or revoke the key in the Claude Console. After that, a session bound to the removed key refuses to restart or resume, and it never falls back to an account; start a new session on the key you have now.

Teams and Enterprise

If your organization's managed Claude Code settings set forceLoginOrgUUID, or set forceLoginMethod to claudeai or console, Claude Code refuses an API-key credential at startup. A key session cannot run on such a machine; use a subscription account that belongs to your organization. Managed settings come from a device-managed file, an MDM profile or your organization's server-managed settings.

On a Hapimatic Cloud VM

The "API Key" option on a Cloud VM's setup page (Cloud User Quickstart) stores an ANTHROPIC_API_KEY in the VM's own environment. It is not one of the keys on this page: you cannot pick it for a session, and Settings → Keys does not show or manage it. To bill a key for the sessions you choose, add it under Settings → Keys.

Each provider's own terms apply to your accounts and keys.