API keys
A key is a credential for one project. It carries a scope, it is shown once, and it can be replaced without downtime.
Using one
curl https://api.stonereason.com/v1/rpc \
-H 'authorization: Bearer xck_…' \
-H 'content-type: application/json' \
-d '{"method":"balance.get","network":"base","address":"0x…"}'A bearer token in the Authorization header. Never in a query
string: a URL ends up in a proxy log, a browser history and an analytics record,
and a key in any of those is a key that has to be rotated.
The secret is shown once
When a key is created the secret appears in exactly one response body and is then gone. StoneReason stores a verifier, not the secret, so there is nothing to reveal later — not to you, not to support, and not to an operator. If you lose it, rotate.
This is the same reason a support request cannot attach one: there is no path by which a key secret reaches anybody after that first response.
Scope
A key carries four scopes, all of them enforced on every request:
- Networks. The chains it may ask about. Empty means none, never all.
- Capabilities. The methods it may call, by wire name. A
method the key does not carry is
OUT_OF_SCOPE, which is a fact about the key rather than about the project. - Transports. HTTP, WebSocket, or both.
- Environment. Inherited from the project, and not overridable by the key.
A key can never reach more than its project was given. Narrowing the key below the project is useful; widening it is not possible.
Restricting where a key may be used
A key may carry an IP allowlist — addresses or CIDR blocks it will be accepted from. An absent or empty list means no restriction, which is what an operator who did not mention it meant. A list that is present and unparseable is refused rather than dropped: a key issued with a restriction its owner believes is in force, and is not, is worse than one with none.
Rotation
Rotating a key issues a new secret under the same key id. The old secret stops working at once; configuration that names the key id keeps working. That is the shape that lets you rotate without a deployment.
If you need an overlap — a window where both the old and the new work — create a second key, move traffic, then revoke the first. Two keys is the overlap mechanism; rotation is the immediate one.
Revocation
A revoked key stops on the next request. There is no cache to
wait out and no propagation delay, because there is one gateway and it reads the
store. A revoked key that is presented afterwards is AUTH_INVALID.
If a key leaks
- Revoke it. From the dashboard, immediately. Do not rotate first — rotation leaves the key id live, and revocation is the thing that stops it.
- Look at the request log. Your dashboard shows every call that key made: when, which network, which method, what happened. That is what tells you whether it was used.
- Issue a new one, scoped to what that workload actually needs rather than to what the old one had.
A key can never broadcast a transaction on this deployment, and StoneReason never holds a private key, so the blast radius of a leaked key is reads and payment watches on the networks you allowed.
Limits
How many keys a project may hold is a Beta limit, and the number is on the Limits page with the reason it is that size.