Rate limits

Every rate limit Token Vault enforces — per-entity floors, the account-wide ceiling, and the penalty box.

Token Vault enforces rate limits at several layers: a floor on each agent/proxy/token, a dynamic ceiling across your whole account, fixed per-IP limits on unauthenticated OAuth endpoints, and an escalating lockout (the "penalty box") for repeat offenders. All of these are on top of anything an ABAC rate_limit policy adds.

Per-entity floors

Each of these applies per agent, proxy, or token — every new entity gets its own fresh allowance.

Scope	Limit	Notes
`agent_credentials`	60 / min per agent	Floor for `GET /api/agents/credentials`
`proxy_mcp`	300 / min per proxy	Floor for MCP proxy traffic
`token_refresh`	10 / hour per token/service	Scheduled + on-demand refresh
`agent_no_grant`	10 / min per agent	`NO_GRANT`/`GRANT_EXPIRED` misses — never a penalty-box strike
`mcp_handshake`	120 / min per proxy/entity	MCP `initialize`/`tools/list` calls
`key_reveal`	20 / hour per agent or proxy	Revealing an agent's or proxy's key
`credential_history`	20 / min per agent	A second, tighter cap on top of `agent_credentials` for paging history

Account-wide ceiling

user_aggregate caps total credential-access traffic across your whole account, regardless of how many agents or proxies you have:

clamp(ceil(1.5 × (60 × active_agents + 300 × proxies)), 600, 3000)

Floor: 600/min even for a brand-new account.
Max: 3000/min no matter how many entities you create.
Grows with your active agent/proxy count so legitimate multi-agent usage isn't throttled, while flattening the payoff of an entity-creation loop to a constant instead of letting it scale linearly.

Other account-wide scopes

Scope	Limit	Notes
`account_export`	5 / hour per account	Exporting your account data
`setup_step`	30 / day per account	Guided webhook-setup wizard telemetry

OAuth / CLI endpoints (per IP)

Endpoint	Limit
MCP OAuth `register`	30 / hour per IP
MCP OAuth `authorize`	30 / hour per IP
MCP OAuth `token`	60 / hour per (IP, client_id)
MCP OAuth `revoke`	60 / hour per IP
MCP OAuth `introspect`	600 / min per IP
`tvault login` (begin)	20 / hour per IP
`tvault login` (exchange)	30 / hour per IP
`tvault login` (refresh)	600 / hour per IP

The penalty box

Beyond plain rate limiting, some scopes escalate repeat violations into a lockout with exponentially growing backoff:

Strike 1 → 1 second, strike 2 → 2 seconds, strike 3 → 4 seconds, doubling each time, capped at 15 minutes.
A strike decays after an hour of no further violations.
agent_no_grant misses are deliberately excluded — a mistyped service name never triggers a penalty-box lockout, only the plain 10/min rate limit above.

Policy-level rate limits

An ABAC rate_limit policy attached to a specific agent, proxy, or token adds its own ceiling on top of everything above. A denial from a policy also returns 429, with the same Retry-After/retryAfter shape as the platform-level limits — the policy field in the response names which policy denied it.

What to do when you hit one

Every rate-limit response carries a machine-readable retry hint: a Retry-After header on REST responses (and retryAfter in the JSON body), or the equivalent in a JSON-RPC -32029 error on MCP calls. Honor it — wait the indicated number of seconds before retrying rather than retrying immediately, especially once the penalty box is involved, since retrying early only resets nothing and burns another strike.