feat(rate-limit): accept API keys in the URL path - #1742
Merged
Conversation
Keys could only be supplied as an X-API-Key header, which makes Studio
unusable from most of the EVM toolchain. MetaMask's "Add network" takes a
URL and has no header field at all; the same is true of foundry.toml,
--rpc-url, and most viem/ethers setups. Every major provider puts the key in
the path for this reason (Alchemy /v2/<key>, Infura /v3/<key>).
This is not hypothetical: an integrator on a shared Studio key told us they
would have to stand up a backend proxy "for them to be able to use it
properly as most of the use comes from testing deployments through
metamask". That proxy's whole job would be turning a URL into a header, and
a shared proxy is also what pushes teams onto one shared key instead of one
key per person.
POST /api/{api_key} now routes to the same JSON-RPC handler, with the header
still accepted for server-side callers. The path wins when both are present,
since it is what the caller typed rather than something an intermediary may
have injected. Only `glk_`-prefixed segments count as keys: any other
segment falls through to anonymous rather than erroring, while a mistyped
real key is still treated as a key so it fails loudly as invalid instead of
silently dropping to anonymous limits.
The middleware's path gate now covers every path the route can match, not
just key-shaped ones. A path served by the route but missed by the gate
would be an unlimited, unauthenticated RPC endpoint, so a test pins that
correspondence.
Keys in URLs get written down in places headers are not, and two of those
were ours: uvicorn access logging is on, and Sentry runs with
send_default_pii and full trace sampling, so request URLs leave the process
on every transaction, not only on errors. api_key_redaction scrubs keys from
both — a logging filter covering uvicorn's args-based access line, and
before_send/before_send_transaction hooks that walk the whole event rather
than known fields. Without this, path keys would be a downgrade on
header-only rather than an improvement.
Contributor
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Member
Author
|
/run-e2e |
|
Member
Author
|
/run-e2e |
4 tasks
MuncleUscles
added a commit
that referenced
this pull request
Aug 18, 2026
…keys to v0.123 (#1743) * feat(rate-limit): meter cheap reads separately and expose usage headers (#1741) Rate limiting was method-agnostic: the middleware checked the quota before the JSON-RPC body was parsed, so `gen_getContractCode` — a single indexed read — cost exactly what a write fanning out to LLM validators cost. That forces the limits to be sized for the expensive case, which starves the cheap read traffic that batch tooling generates. Reads that never enter the GenVM now meter into their own bucket at RATE_LIMIT_READ_MULTIPLIER (default 10x) of the tier limits. The standard bucket keeps its key shape and numbers, so limits in flight at deploy time carry over rather than resetting. The allowlist is maintained by hand and deliberately conservative. Two methods that read like lookups are excluded because they build a Node backed by a GenVMManager (gen_getContractSchema, gen_getContractSchemaForCode), and eth_call is excluded for the same reason despite appearing in the DISABLE_INFO_LOGS_ENDPOINTS env list that otherwise looks like the natural source for this. Anything ambiguous — unparseable, oversized, or a batch with one expensive member — is charged to the stricter bucket. Responses now carry X-RateLimit-Limit/Remaining/Reset/Window/Bucket for the window closest to exhaustion, so clients can pace themselves instead of discovering the ceiling by hitting it. Reset is the time until the oldest entry ages out, which is the honest answer for a sliding window. These are listed in the CORS expose_headers, without which browsers hide them from JS. Finally, gen_getContractCode no longer loads the whole contract state to read one slot out of it. ContractSnapshot pulls the entire `data` JSONB — every storage slot the contract owns — which for a contract holding a large vector store is a substantial fetch and deserialize on a call that batch tooling polls hard. The slot is now extracted in SQL. Postgres still detoasts the JSONB server-side, so this narrows transfer and parse cost rather than eliminating the read; legacy and undeployed row shapes defer to the original path to keep their error semantics intact. The Lua script gains a test that actually executes it under a stubbed redis.call. It was previously covered only through mocked evalsha, so an error in the script body would have surfaced first in production, on every /api request. * feat(rate-limit): accept API keys in the URL path (#1742) Keys could only be supplied as an X-API-Key header, which makes Studio unusable from most of the EVM toolchain. MetaMask's "Add network" takes a URL and has no header field at all; the same is true of foundry.toml, --rpc-url, and most viem/ethers setups. Every major provider puts the key in the path for this reason (Alchemy /v2/<key>, Infura /v3/<key>). This is not hypothetical: an integrator on a shared Studio key told us they would have to stand up a backend proxy "for them to be able to use it properly as most of the use comes from testing deployments through metamask". That proxy's whole job would be turning a URL into a header, and a shared proxy is also what pushes teams onto one shared key instead of one key per person. POST /api/{api_key} now routes to the same JSON-RPC handler, with the header still accepted for server-side callers. The path wins when both are present, since it is what the caller typed rather than something an intermediary may have injected. Only `glk_`-prefixed segments count as keys: any other segment falls through to anonymous rather than erroring, while a mistyped real key is still treated as a key so it fails loudly as invalid instead of silently dropping to anonymous limits. The middleware's path gate now covers every path the route can match, not just key-shaped ones. A path served by the route but missed by the gate would be an unlimited, unauthenticated RPC endpoint, so a test pins that correspondence. Keys in URLs get written down in places headers are not, and two of those were ours: uvicorn access logging is on, and Sentry runs with send_default_pii and full trace sampling, so request URLs leave the process on every transaction, not only on errors. api_key_redaction scrubs keys from both — a logging filter covering uvicorn's args-based access line, and before_send/before_send_transaction hooks that walk the whole event rather than known fields. Without this, path keys would be a downgrade on header-only rather than an improvement. * feat(rate-limit): classify the v0.123-only RPC methods The ported allowlist predates three methods that exist only on this branch. sim_getFeeConfig and gen_getTransactionStatusDetails are cheap reads — a config lookup and a transactions_processor read respectively, neither touching the GenVM. sim_estimateTransactionFees is not. It takes validators_manager and genvm_manager and runs the contract through sim_call to measure fees, so it costs a full execution. Worth flagging because eth_estimateGas *is* allowlisted — that one returns a hardcoded constant. The names are nearly identical and the costs are not, which is the same shape of trap as eth_call and the two schema methods already documented here.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
POST /api/{api_key}now routes to the same JSON-RPC handler, so a key can be supplied in the URL as well as via theX-API-Keyheader.glk_-prefixed segments count as keys — any other segment falls through to anonymousbackend/protocol_rpc/api_key_redaction.pyscrubs keys from logs and SentryWhy
The header-only design makes Studio unusable from most of the EVM toolchain. MetaMask's "Add network" takes a URL and has no header field at all, and the same is true of
foundry.toml,--rpc-url, and most viem/ethers setups. Every major provider puts the key in the path for exactly this reason (Alchemy/v2/<key>, Infura/v3/<key>, QuickNode, Ankr).This is not hypothetical. An integrator we issued a key to said they would have to stand up a backend proxy "for them to be able to use it properly as most of the use comes from testing deployments through metamask". That proxy's entire job would be turning a URL into a header — and a shared proxy is also what pushes a team onto one shared key rather than one key per person, which loses per-user attribution and means one heavy user starves the rest.
Secondary:
X-API-Keyis not CORS-safelisted, so every browser call currently pays a preflightOPTIONSbefore thePOST. The path form has no preflight.Testing done
appobject that both/apiand/api/{api_key}register, and that/api/explorer/*is not shadowed:POST /api/explorer/statscorrectly 405s to the explorer GET route rather than being captured by the path param, and/api/a/b404sDecisions made
Invalid API keyrather than silently falling back to anonymous limits. Silent downgrade is the exact confusion an earlier user hit ("check the header is actually attached"). A segment that is not key-shaped at all is not an error — it is simply anonymous.access_log=Truesends full paths to stdout, and Sentry runs withsend_default_pii=Trueandtraces_sample_rate=1.0, so request URLs leave the process on every transaction, not just errors. Shipping path keys without this would have been a downgrade on header-only rather than an improvement.request.url, the transaction name, breadcrumbs and span descriptions — missing one defeats the purpose.Checks
Reviewing tips
_is_rpc_pathand the route decorators must stay in lockstep. That is the one place a mistake is dangerous rather than merely wrong.glk_+ 4-or-more hex so partial keys are caught too.Referer. That is the accepted trade every provider makes, and it argues for making key rotation self-serve. Rotation is currently impossible on prod becauseADMIN_API_KEYis unset there, which is worth fixing separately.install_log_redaction()runs beforesentry_sdk.init, so the filter is in place before anything can log.User facing release notes
https://studio.genlayer.com/api/<key>— in addition to theX-API-Keyheader. This makes keyed access work from MetaMask, Foundry, and any other tool that accepts only an RPC URL.