API keys

An API key identifies the account on every request. It determines the rate limit, the chains and origins from which requests are accepted, and the account to which usage is billed. An account can have up to 25 active keys, for example one per application or environment, each with its own name and limits.

Creating a key

Sign in at dashboard.willow.tech and open Keys. Enter a name for the key and, optionally, limits. The key is displayed once, at creation. Willow stores only its SHA-256 hash, so a lost key cannot be displayed again and must be rotated instead.

A new key takes effect within seconds and requires no restart.

Sending the key

In the path, as the final segment of the URL:

https://api.willow.tech/v1/rpc/{chainId}/{YOUR_KEY}

This form is compatible with every library, since the entire endpoint is a single URL.

In a header, with the key omitted from the path:

POST https://api.willow.tech/v1/rpc/{chainId}
Authorization: Bearer {YOUR_KEY}

X-API-Key: {YOUR_KEY} is also accepted. A header keeps the key out of URLs, which are commonly written to logs, error reports, and browser history. Quick start shows the header form for each library.

Key security

Any holder of a key can spend the account balance. Keys should be kept on a server and out of client-side code, public repositories, and shared logs. If a browser application must call Willow directly, issue it a separate key restricted to the application’s origins (see below). The origin restriction prevents other websites from using a leaked key in a browser, but a script outside a browser can send any Origin header. A browser key should therefore be treated as public and given a low rate limit.

Limits per key

Each key can carry its own limits. A limit that is not set defaults to the plan limit or to Willow’s default.

Limit	Effect
Name	A label shown in the dashboard and in usage.
Requests per second	A rate limit lower than the plan’s. A key never exceeds the plan limit.
Chains	The chains this key may call. Requests to other chains are refused with HTTP 403.
Allowed origins	The browser origins (https://app.example.com) this key accepts. Requests from other origins are refused with HTTP 403.
Proofs	Whether this key may request log proofs.
Max blocks per proof job	The maximum number of unproven blocks a single proof request from this key may queue.
Max open proof jobs	The maximum number of this key’s proof jobs that may be open concurrently on each chain.

The plan’s rate limit applies to the account: all of the account’s keys share its requests per second. A key with a lower limit of its own never exceeds that limit. Proof job limits are clamped to the plan’s limits in the same way.

Rotating a key

Rotation creates a new key with the same name and limits and revokes the old key. The old key stops working within seconds, so the new key should be deployed first where an interruption is not acceptable. In the dashboard, use Rotate on the key.

Revoking a key

Revocation disables a key within seconds. Subsequent requests with it are refused with HTTP 401:

{"error":{"code":-32000,"message":"invalid API key"},"id":null,"jsonrpc":"2.0"}

If a key is leaked and the dashboard is not accessible, the key can revoke itself:

curl -X DELETE https://api.willow.tech/account/rpc/keys/{KEY_ID} \
  -H "Authorization: Bearer $LEAKED_KEY"

KEY_ID is the key’s identifier (key_…), shown in the dashboard or returned by GET https://api.willow.tech/account/rpc/keys with the same header. A key used this way can read its own account, revoke itself, and choose, cancel, or resume a plan paid from the balance, but cannot create keys, change limits, or change caps.

Key errors

HTTP	Message	Meaning
401	invalid API key	The key does not exist or was revoked.
401	API key required: …	No key was provided in the path or a header.
401	this API key is suspended	The account is suspended, for example after a failed payment and its grace period.
402	payment required: …	The balance is exhausted. See Limits and errors.
403	this API key is not enabled for chain N	The key is restricted to other chains.
403	this API key does not take requests from this origin	The key is restricted to other origins.
429	rate limit exceeded	The key’s requests-per-second limit was exceeded.
429	too many requests with an invalid API key from this address	Too many requests were sent with nonexistent keys. Wait, and correct the key.