API keys as a last resort, with a spend cap

Every heavy Claude Code user eventually has the same thought at the same bad moment: "My subscriptions are all out, the agent is halfway through something, and I have an API key sitting right there. Why can't it just use that?"

It can. The trick is making sure it uses the key only then, and that "only then" doesn't quietly turn into a surprise bill. So that's how we built it.

Subscriptions first, keys last#

In Shuriken, an API key is a source like any of your subscriptions. Press Switch settings at the top of Sources, and under When every subscription is out there's a switch: Switch to API keys. It's off until you turn it on.

With it on, the order is simple:

1. Your chats run on your subscriptions, switching between them as each one reaches your switch point.
2. Only once every subscription that could take the chat is out do API keys and endpoints step in.
3. When a subscription has room again, chats go back to it.

The move is visible. A Switched to … card in the chat says which source took over and why, so you always know when you're on metered time.

A spend cap on every fallback run#

Each time your chats fall back to API keys, that stretch gets a spend cap (Spend cap per fallback in the same section). Past the cap, the keys stop taking chats and the work waits for a subscription to have room. It's on by default, starting at 25 US dollars, and you can change the amount. The cap counts the whole run for that agent's provider, across every key the run touches. It is not a cap per key, so three Anthropic keys don't get three times 25 dollars.

The cap belongs to the fallback run, not to the calendar. When a subscription takes chats back, the run ends, and the next time you fall back you start with a fresh cap. You can also turn the cap off. Then a fallback keeps spending until a subscription has room, and Shuriken still counts what it spends.

One detail we're glad we got right: if you pick an API key yourself and press Use, that isn't a fallback. You chose it on purpose, so the cap doesn't step in and stop you.

Why keys go last#

Because they're metered. A subscription gives you a 5-hour window and a weekly limit for a fixed monthly price. An API key bills for every token. In Anthropic's words, "Claude Code charges by API token consumption" (Claude Code docs).

That difference is also behind a classic trap. Anthropic's help centre warns that if an ANTHROPIC_API_KEY environment variable is set, "Claude Code will use this API key for authentication instead of your Claude subscription", which means API charges rather than your plan's included usage (Claude Help Center). One forgotten line in a shell profile and your "free" sessions aren't free.

In Shuriken a key never sneaks in like that. It's a source you added on purpose, it takes chats only in the order above, and the switch to it is marked in the chat.

If you're still deciding between a plan and a key in the first place, our guide to Claude Code on an API key or a subscription, in the links below, does the sums.

How to add a key as a source#

1. Open Settings › Sources, choose Add source and pick the agent, say Claude Code.
2. Choose API key and paste it. For an Anthropic- or OpenAI-compatible service, choose Custom endpoint instead and fill in its Address and key.
3. For an endpoint, give it a Label if you like and press Test: Shuriken checks that it answers and tells you how many models it reached.
4. Press Switch settings at the top of Sources, turn on Switch to API keys and set Spend cap per fallback.

That's it. The key now sits at the back of the line, which is where it belongs. It shows on the Sources page next to your subscriptions, and source switching handles the rest.

Shuriken takes no cut of any of this, by the way. We never bill model usage: the provider bills your key directly. More on why in Bring your own plans.

A fallback with no bill per token#

Keys are a fine safety net, but it's still money. Since 5.1, local models are sources too: point one at Ollama, LM Studio or any OpenAI- or Anthropic-compatible address on your own computer or network. A local model is an endpoint, so it never goes ahead of a subscription. It takes chats when you pick it, or once every subscription is out, and on your own hardware there's no bill per token. Whether a local model can carry on your particular task is another question, but for a lot of chores it can.

Try Shuriken, add your plans first and your key last, and let the order do the worrying.