> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate GoldRush JSON-RPC requests with the Authorization header. Drop-in patterns for ethers, viem, web3.js, web3.py, and curl.

GoldRush JSON-RPC authenticates every request by an `Authorization: Bearer <key>` HTTP header. Your API key never appears in the URL, keeping it out of server logs, browser history, screenshots, and error reports. This matches the pattern used across the rest of the GoldRush product family.

The same GoldRush API key works across every GoldRush product: Foundational, Streaming, Pipeline, Hyperliquid, x402, and JSON-RPC. One key, every product.

## The header

```http theme={null}
Authorization: Bearer <GOLDRUSH_API_KEY>
Content-Type: application/json
```

`Content-Type: application/json` is required: JSON-RPC payloads are always JSON.

## Per-library setup

`viem`, `ethers`, `web3.js`, and `web3.py` all support custom request headers, but the boilerplate differs slightly between them. Copy whichever one applies.

<CodeGroup>
  ```typescript ethers v6 theme={null}
  import { ethers } from "ethers";

  const url = "https://rpc.goldrushdata.com/v1/eth-mainnet";
  const fetchReq = new ethers.FetchRequest(url);
  fetchReq.setHeader("Authorization", `Bearer ${process.env.GOLDRUSH_API_KEY}`);

  const provider = new ethers.JsonRpcProvider(fetchReq);
  ```

  ```typescript viem theme={null}
  import { createPublicClient, http } from "viem";
  import { mainnet } from "viem/chains";

  const client = createPublicClient({
    chain: mainnet,
    transport: http("https://rpc.goldrushdata.com/v1/eth-mainnet", {
      fetchOptions: {
        headers: {
          Authorization: `Bearer ${process.env.GOLDRUSH_API_KEY}`,
        },
      },
    }),
  });
  ```

  ```javascript web3.js theme={null}
  import { Web3 } from "web3";

  const provider = new Web3.providers.HttpProvider(
    "https://rpc.goldrushdata.com/v1/eth-mainnet",
    {
      headers: [
        { name: "Authorization", value: `Bearer ${process.env.GOLDRUSH_API_KEY}` },
      ],
    }
  );
  const web3 = new Web3(provider);
  ```

  ```python web3.py theme={null}
  from os import environ
  from web3 import Web3

  w3 = Web3(Web3.HTTPProvider(
      "https://rpc.goldrushdata.com/v1/eth-mainnet",
      request_kwargs={
          "headers": {
              "Authorization": f"Bearer {environ['GOLDRUSH_API_KEY']}",
          },
      },
  ))
  ```

  ```bash curl theme={null}
  curl https://rpc.goldrushdata.com/v1/eth-mainnet \
    -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
  ```
</CodeGroup>

## Error responses

Authentication and credit failures return the standard JSON-RPC error envelope with an HTTP status code matching the failure mode.

| HTTP                    | JSON-RPC code | Meaning                                     | Resolution                                   |
| ----------------------- | ------------- | ------------------------------------------- | -------------------------------------------- |
| `401 Unauthorized`      | `-32001`      | Missing or malformed `Authorization` header | Add the `Authorization: Bearer <key>` header |
| `403 Forbidden`         | `-32002`      | Key is valid but lacks JSON-RPC entitlement | Contact support to enable JSON-RPC           |
| `402 Payment Required`  | `-32003`      | Insufficient credits                        | Top up your credit balance                   |
| `429 Too Many Requests` | `-32005`      | Rate limit exceeded                         | Back off and retry after `Retry-After`       |

Example failure body:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "missing or invalid Authorization header"
  }
}
```

## Rotating keys

Generate a new key in the [GoldRush dashboard](https://goldrush.dev), update your environment variable, and revoke the old one. There is no per-product key rotation: rotating once cycles the key for every GoldRush product.

<Tip>
  For zero-downtime rotation, set both the old and new key as accepted in your config, deploy with the new key, then revoke the old key once traffic has cut over.
</Tip>

## Related

<CardGroup cols={2}>
  <Card title="Quickstart" href="/goldrush-json-rpc/quickstart" icon="rocket">
    Make your first call.
  </Card>

  <Card title="Pricing" href="/goldrush-json-rpc/pricing" icon="coins">
    Per-method credit rates for the Edge tier.
  </Card>
</CardGroup>