An RPC API key that ships in browser code is not a secret. It is in your JavaScript bundle and in every request shown in the network tab, and anyone who opens the developer tools can copy it. Environment variables do not change that: a value inlined into a frontend build is as public as the rest of the bundle.
So the useful question is not how to hide the key. It is how little a copied key can do, and how quickly you can replace it. This guide covers both, using what NodeFlare accounts now support: several keys per account, restrictions per key, and rotation with an overlap period. The same approach works with any RPC provider that offers comparable controls; the last section explains how to check.
What a leaked key costs you
An RPC key cannot move funds. It authorises requests, and requests are billed to your account. Someone holding your key can:
- Spend your monthly quota. On NodeFlare, quota is measured in compute units (CU) and heavy methods weigh more:
eth_getLogscosts 25 CU,eth_callcosts 5,eth_blockNumbercosts 1 (full table). The Free plan's 3,000,000 CU is 120,000eth_getLogscalls. At the Free plan's 10 requests per second, single calls get through that in 12,000 seconds, which is 3 hours and 20 minutes. - Take your requests per second. The rate limit belongs to the account. Traffic on a copied key competes with your own application, which then receives HTTP
429. - Stop your application. Once the quota is gone, your own requests get
monthly_limit_reacheduntil the reset or a top-up.
Keys leak in ordinary ways: a frontend bundle, a public repository, a CI log, a screenshot, a support ticket. A key that only ever lives on a server leaks less often, but it does leak.
One key per purpose
Every NodeFlare account has a main key. You can add named keys next to it in the dashboard and revoke each one on its own. The number of keys, including the main key, depends on the plan:
| Plan | Keys, including the main key |
|---|---|
| Free | 2 |
| Hacker | 3 |
| Starter | 5 |
| Pro | 10 |
| Scale | 25 |
Two properties matter for planning:
- All keys share the plan. One monthly CU quota and one rate limit for the whole account. A second key does not add quota or requests per second, and a restricted key does not get its own budget. See rate limits.
- Restrictions exist on additional keys only. The main key is never restricted, so it should be the key that stays on a server.
Separate keys do not isolate quota, but they give you three things a single key cannot: you can revoke one without touching the others, you can restrict each to its job, and the dashboard shows how many compute units each additional key used this month, so you can see which one is being abused.
What each restriction does, and what it does not
An additional key can carry up to four allowlists. Each is optional and holds at most 20 entries. A request has to pass every list that is set.
| Restriction | Entries | Stops | Does not stop |
|---|---|---|---|
| Origins | app.example.com, *.example.com | Another website using a copied key from its visitors' browsers | A script outside a browser, which can send any Origin header it likes |
| IP addresses | 203.0.113.7, 10.0.0.0/8, IPv6 addresses and ranges | Use of the key from any other address | Anything running on the allowed machines; no use for browser keys, whose users have arbitrary addresses |
| Chains | eth, base | Use of the key on chains your app does not serve | Use on the chains you did allow |
| Methods | eth_call, net_* | Expensive or irrelevant calls such as eth_getLogs, trace_*, debug_* | Any volume of the allowed methods |
Some details, taken from how the gateway matches requests:
- Origins are hosts. Enter
app.example.com, without a port; a pastedhttps://prefix is removed. The port and scheme of the incomingOriginheader are ignored.*.example.commatches subdomains at any depth but notexample.comitself, so add both if you need both. - A request without an
Originheader fails an origin list. That includes server-side rendering and scripts. A key restricted to origins is a browser key and nothing else; give your server its own key. - Chains are the names in the endpoint URL, the
<chain>part ofhttps://rpc.nodeflare.app/<chain>/v1/<key>. - Methods are exact names or a namespace such as
eth_*. The list is applied to every call in a batch and to every WebSocket message. - A key with a method list only accepts plain JSON-RPC. Each call may contain
jsonrpc,id,methodandparamsand nothing else, and no object insideparamsmay have a member namedmethod. The check has to read the request exactly as the node will, and a request that leaves room for interpretation is refused. Standard JSON-RPC requests from viem and ethers have this shape. - A key restricted to chains or methods cannot be used on the data API or the answer endpoint, because those are not bound to one chain or method.
The plain statement about origin restrictions: they stop other websites, not determined people. A browser sets the Origin header itself and page scripts cannot change it, which is why the check holds against a site that copies your key. Outside a browser the header is one command-line flag. A key restricted to your origin can still be driven from a script that pretends to be your site.
That is why a browser key should carry a method list as well. If the only methods it accepts are the cheap reads your interface needs, a forged request can still spend quota, but only through those methods and at their CU weight, and it cannot reach eth_getLogs, trace_* or debug_*. Restrictions narrow what a key can do. They do not cap how much, and they do not make a public key safe.
A practical setup
A layout for a typical application with a backend, a staging environment and a browser frontend:
| Key | Lives in | Restrictions |
|---|---|---|
| Main key | Production backend secret store | None possible; never leaves the server |
staging | Staging secrets | IP addresses of the staging hosts if they are fixed; the chains you test on |
frontend | Browser bundle | Your origins, the chains the interface uses, a short method list |
This uses three keys, which is the Hacker plan's limit. On Free, with two keys, keep the main key on the backend and spend the additional key on the frontend. Current plans are on the pricing page.
For the frontend method list, start from what a read-only interface usually calls and adjust:
eth_chainId
eth_blockNumber
eth_call
eth_getBalance
eth_estimateGas
eth_gasPrice
eth_feeHistory
eth_maxPriorityFeePerGas
eth_getTransactionReceiptWhich methods your libraries call depends on their version and configuration, so run the application against the restricted key before release and look for 403 responses in the network tab. Each refusal names the method, which tells you what to add. Transactions signed in a user's wallet are normally broadcast by the wallet through its own RPC, so the frontend key often does not need eth_sendRawTransaction; check your own flow.
For local development, prefer a separate key over adding localhost to the production frontend key. localhost is a valid origin entry, and anyone can serve a page from it.
Using the frontend key
With viem:
import { createPublicClient, http } from "viem";
import { base } from "viem/chains";
// Public by design: restricted to your origins, Base and a few read methods.
const FRONTEND_KEY = "nf_live_YOUR_FRONTEND_KEY";
export const client = createPublicClient({
chain: base,
transport: http(`https://rpc.nodeflare.app/base/v1/${FRONTEND_KEY}`),
});
const block = await client.getBlockNumber();With ethers v6:
import { JsonRpcProvider } from "ethers";
const provider = new JsonRpcProvider(
"https://rpc.nodeflare.app/base/v1/nf_live_YOUR_FRONTEND_KEY",
8453,
{ staticNetwork: true },
);
const block = await provider.getBlockNumber();What a refusal looks like
You can test a restricted key from the command line by setting the header yourself, which also demonstrates the limit described above:
curl -i https://rpc.nodeflare.app/base/v1/nf_live_YOUR_FRONTEND_KEY \
-H 'Content-Type: application/json' \
-H 'Origin: https://app.example.com' \
--data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'With an allowed origin, chain and method, this returns a normal JSON-RPC result. Leave the Origin header out, or send a different one, and the gateway answers HTTP 403:
{
"error": "key_restricted",
"message": "Request refused: this API key is restricted to other origins. Change the restrictions of this key at nodeflare.app/app/dashboard."
}A method outside the list gets the same status and error with a message that names it:
{
"error": "key_restricted",
"message": "Request refused: this API key is not allowed to call eth_getLogs. Change the restrictions of this key at nodeflare.app/app/dashboard."
}A refused request is not charged. Note that the body is a plain JSON object with error and message, not a JSON-RPC error envelope, so client libraries report it as an HTTP failure. On a WebSocket, a refused method gets a JSON-RPC error instead and the socket stays open.
Rotating a key without downtime
Replacing a key in one step means that every deployment still holding the old key fails until it is redeployed. For a frontend it is worse: browsers keep running the cached bundle with the old key for as long as the tab stays open.
Rotation with an overlap avoids that. When you rotate a key in the dashboard, you choose how long the old one keeps working: 1 hour, 24 hours, 7 days, or not at all. During that period both keys are accepted. A previous key in its overlap does not count towards your plan's key limit, and the previous key of a restricted key keeps the same restrictions.
A routine rotation:
- Rotate the key and pick an overlap longer than your slowest rollout. For a browser key that includes the time old bundles stay cached.
- Deploy the new key everywhere the old one was configured.
- Watch the dashboard. It lists the old key with the time it has left and shows whether it is still being used.
- When the old key is no longer in use, stop it early or let it run out.
A leaked key is the opposite case: choose "stop it now" and accept the short interruption while you deploy the replacement. An overlap would keep the leaked key alive for whoever holds it. A stopped or revoked key is refused in every region within a few minutes, not instantly, so do not treat saving a change as the moment it applies everywhere.
Rotating on a schedule is worth doing even without an incident, because it proves the procedure works before you need it in a hurry.
When a public key is the wrong tool
If the browser needs methods you would not want anyone to call at your expense, such as wide eth_getLogs ranges or traces, do not put them on a public key. Send those requests to your own backend, authenticate your users there, apply your own per-user limits, and let the backend call the RPC with a server key. That costs you an extra hop and a service to run, and it is the only arrangement in which the RPC key is actually secret.
Many applications end up with both: a narrowly restricted browser key for cheap reads, and a backend route for everything heavy.
The same checklist for any provider
The mechanism differs by provider, the questions do not. For any RPC service, check the current documentation for:
- Several keys or projects per account, so one credential can be revoked alone.
- Allowlists by origin, IP address, chain and method, and which plans include them.
- Whether a refused request is billed.
- How limits are scoped: per key, per project or per account. This decides whether an abused browser key can starve your backend.
- Rotation: whether old and new credentials can be valid at the same time, and how long a revocation takes to apply.
- Per-key usage figures, so you can tell which key is responsible for a spike.
Whatever the answers, the principles carry over: treat a browser key as public, give every environment its own key, allow only what each key needs, and practise rotation.
FAQ
Can I hide an RPC API key in a frontend application?
No. Anything the browser sends can be read by the person using the browser. Restrict the key to your origins and a short method list, or route requests through your own backend.
Does an origin restriction make a frontend key safe?
No. It prevents other websites from using the key through their visitors' browsers. A script outside a browser can forge the Origin header. Combine it with a method list and watch per-key usage.
Do additional keys add quota or rate limit?
No. All keys of a NodeFlare account share one monthly compute-unit quota and one rate limit. See rate limits.
Can I restrict the main key?
No. Restrictions exist on additional keys; the main key is never restricted. Keep it on a server.
Is a refused request charged?
No. A request outside a key's restrictions gets HTTP 403 with "error": "key_restricted" and is not charged.
How do I rotate a key that has leaked?
Rotate it with no overlap ("stop it now") and deploy the new key. The old key is refused in every region within a few minutes.
Next steps
- Authentication reference: key format, restrictions and rotation.
- Rate limits and compute units: what each method costs.
- Production integration practices: server-side calls and handling limits.
- Pricing: plans, monthly quota and rate limits.
- Open your dashboard to add, restrict or rotate a key, or create a Free account.