Per-agent API keys or per-agent budgets: what each stops
A per-agent API key says which agent called and lets you revoke one agent without touching the rest. It does not cap anything by itself. A cap is a separate counter, and each provider attaches it at a different level: OpenRouter to the key, OpenAI to the project. Per the pages read on 16 November 2026, OpenRouter attributes spend to the key's creator, and OpenAI documents no per-key spend limit.
A key names the caller, a budget counts the spend
Two things get mixed up when people say "one key per agent". The key is a credential. It tells the provider which account a request belongs to, and revoking it ends that access. A budget is a counter with a threshold. It knows nothing about who is calling until someone attaches it to a key, a project or a workspace.
The useful question is therefore where each provider attaches the counter. That decides whether a key per agent gives a cap per agent, or only a name per agent. The answer differs between the two providers below, both read on 16 November 2026.
OpenAI attaches the cap to the project, not the key
OpenAI's spend limits guide separates two controls. A spend alert "Sends a notification; API traffic continues". A hard spend limit makes affected requests return a 429, and the page adds: "Spend alerts do not enforce a cap."
The scope of the hard limit is the organization or one project. The page lists the error codes:
organization_spend_limit_exceededwhen the organization limit is reached.project_spend_limit_exceededwhen a project limit is reached.
The setting is a "Monthly spend limit" with an "Enforce a hard limit" switch, found under the project's Limits page. The guide describes no spend limit on an individual API key. It also says "Enforcement is not instantaneous, so recorded spend can slightly exceed the configured amount."
The production best practices page covers the identity half. It advises: "Use a project service account for an application's identity instead of depending on an individual developer's key." It also recommends an expiry date on every project key, and says administrators can set a maximum key lifetime. Neither feature caps spend.
For OpenAI, then, a cap per agent means a project per agent. Keys inside one project share that project's limit, so two agents on two keys in one project can still drain the same counter. The limit is monthly. A daily cap per agent is a different problem, covered in how to set a daily spending limit for an AI agent.
OpenRouter attaches the cap to the key, and counts the creator
OpenRouter puts a credit limit on the key itself. The shared agent keys guide lists three fields:
limit: the cap in USD.limit_reset:daily,weeklyormonthly, resetting at midnight UTC. Unset means a lifetime cap.include_byok_in_limit: whether spend through your own provider keys counts. The default isfalse.
A cap is set with one call, using a management key:
curl -X PATCH https://openrouter.ai/api/v1/keys/{key_hash} \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"limit": 200, "limit_reset": "monthly", "include_byok_in_limit": true}'
That is the example from the guide. Two details in the same page change what a key-level cap means.
The BYOK default comes first. Per the guide, a key that runs on bring-your-own-key providers never reaches its limit while the toggle stays at its default of false. An agent on that traffic can sit under a cap that never trips.
Next, who the counter belongs to. The guide states: "OpenRouter attributes spend to the creator of an API key, not to whoever calls it." A member guardrail budget applies to the keys that member created. A workspace-owned key, which is how an admin typically creates a key for an agent or a CI job, has no creator. The guide's table shows what reaches it:
| Control | Applies to a workspace-owned key? |
|---|---|
| Member guardrail | No: there is no member to resolve |
| Workspace default guardrail | Yes |
| Guardrail assigned to the key | Yes |
| Workspace budget | Yes: all keys in the workspace draw from one pool |
| Key credit limit | Yes: the key's own hard cap |
The spend controls guide adds the practical consequence: "A shared admin-owned key used by an entire team draws against the admin member budget, not against each user who calls it." A strict member guardrail can therefore sit in a workspace while an agent key spends outside it.
The workspace budget is one pool per workspace. The shared agent keys guide says there is no way today to give two teams in one workspace separate pooled budgets, so independent teams need separate workspaces.
What the cap returns decides whether the agent stops
When the key limit trips, the agent needs to know it is a stop signal and not a retry. The sources disagree on the status code, so match on the field.
The shared agent keys guide says requests "fail with 403 Forbidden and a Key limit exceeded message". The limits reference lists openrouter_key_limit in its 402 section ("the API key's credit limit is exhausted") and again in its 403 section, where limit_source is openrouter_guardrail_budget, openrouter_workspace_budget or openrouter_key_limit. The same page says "branch on limit_source, not on the hint text."
The one case that is safe to retry is openrouter_in_flight_budget, which carries a Retry-After header. The 403 budget errors carry none, because "the wait is usually hours or days". A retry loop that treats every 4xx as transient will spin against a key cap. The infinite loop entry covers the layers around that.
Where a per-agent key still leaves spend uncapped
Four gaps follow from the pages above.
- Shared counters. On OpenAI, keys in one project share the project's limit. On OpenRouter, a member guardrail aggregates across all the keys that member created, and the guide notes that a new key "does not reset the member-level counter".
- Whoever holds the management key. The call above takes
limitas a parameter. The credential that can create and patch keys can raise any cap, so it belongs outside the agent's reach. - A bearer key proves nothing about the sender. A stolen key spends its cap from anywhere until the cap or the revocation stops it. Proof of possession addresses that, and the stolen key entry walks through how.
- Window shape. OpenAI's limit is monthly, and OpenRouter's resets daily, weekly or monthly at midnight UTC. Neither window has a rate component or reads a single call, so a monthly cap of 200 USD does not stop a loop from spending the whole amount within hours.
None of this makes provider-side caps a poor choice. They are enforced by the party that bills you, they are not a setting inside the agent's own process, and they hold even if your own gateway is bypassed. The right pattern is a provider cap as the outer limit, with a tighter counter in front of it. LiteLLM's key budgets are one such counter, with their own documented limits.
A rule of thumb for choosing
| You need | Use |
|---|---|
| To revoke one agent without touching others | A key per agent |
| A provider-enforced cap per agent on OpenAI | A project per agent, with a hard limit |
| A provider-enforced cap per agent on OpenRouter | A credit limit on each key, plus a workspace budget as the pool |
| A cap that a shared or workspace-owned key cannot escape | A key limit or key guardrail, not a member guardrail alone |
| A daily window on OpenAI | A counter in front of the provider |
Where Mandare fits
Mandare moves the counter from the key to the agent. The concepts page describes a mandate as signed spend caps "per transaction / day / task / total", signed by the owner for one agent. The door reserves the estimated cost before each call. In the demo, one agent under a mandate of 5 EUR per call, 20 EUR per day and 100 EUR in total is refused on call 72:
agent=did:mandare:dev-agent caps: tx 5 / day 20 / total 100 EUR
…
call # 72 403 DENIED — THE LOOP DIES HERE
code: PER_DAY_EXCEEDED
reason: per-day budget exceeded: reserved 0.00 EUR + settled 19.723587 EUR + estimate 0.278853 EUR > cap 20.00 EURThe transcript is in the demo file. It runs against a mock provider with no API keys: the enforcement is real, the money is not. The mandate, not a provider key, carries the cap.
The providers page also describes the combination this entry recommends. With an OpenRouter management key, "the door can mint per-agent runtime keys with hard USD caps enforced by OpenRouter itself". The limits of that statement, as of v0.1.0 and the repository state at commit 327442e:
- The repository holds the client, [
OpenRouterProvisioningClient](https://github.com/mandarelabs/mandare/blob/327442e714d35632c2cfc911f7839b69cbb0e4c7/packages/gateway/src/provisioning.ts), which creates, disables, deletes and rotates capped keys. No command in the CLI reference calls it, so no end-to-end flow is claimed here. - A source comment in
apps/cli/src/kill.tslists disabling the OpenRouter key as later work. Do not assumemandare killalso disables the provider-side key. - The door proxies Anthropic
POST /v1/messagesand OpenAI or OpenRouterPOST /v1/chat/completions, as the providers page lists. - The cap holds given a correct price table. Models without a price are refused. We make no claim that a cap cannot be exceeded under any condition.
- There is no hosted service, no external audit, and the card rail has been tested against a Stripe mock, with no live test-mode run yet.
Questions
Does a separate API key per agent limit its spending?
Not by itself. A key is a credential; the cap is a separate setting. OpenRouter lets you set a credit limit on the key. OpenAI's spend-limit page describes limits at the organization and project level and does not describe a per-key limit, so one project per agent gives you a per-agent cap there.
What does OpenRouter return when an agent key hits its limit?
The two OpenRouter pages read on 16 November 2026 disagree on the status code: the limits reference lists openrouter_key_limit under 402 errors and again under 403 budget errors, and the shared-keys guide says 403. Branch on error.metadata.limit_source, which the reference tells readers to do, not on the status code.
Why does a shared agent key look uncapped on OpenRouter?
Spend is attributed to the key's creator, not to the caller. A workspace-owned key has no creator, so member guardrail budgets never apply to it. It needs its own credit limit, a guardrail assigned to the key, or the workspace budget.
Does OpenAI offer a daily cap per agent?
Not from the spend-limit page read on 16 November 2026, which describes a monthly limit for the organization or a project. A daily window needs a counter in front of the provider, or a provider that resets keys daily, such as OpenRouter.
Sources
- Capping Shared Agent Keys (OpenRouter documentation) · OpenRouter
- Spend Controls (OpenRouter documentation) · OpenRouter
- API Rate Limits and Credit Limits (OpenRouter documentation) · OpenRouter
- Spend limits (OpenAI API documentation) · OpenAI
- Production best practices (OpenAI API documentation) · OpenAI
Run it yourself: 3 commands, no API keys.
github.com/mandarelabs/mandare →