# API Authentication

Dwellir accepts `X-Api-Key` or an API key in the endpoint URL path for HTTP and WebSocket connections. gRPC clients must use lowercase `x-api-key` request metadata.

Use the header when your tracing or logging system records request URLs. Use the URL path when your client cannot set custom headers.

## Header authentication

### HTTP and JSON-RPC

Set the `X-Api-Key` header on each request:

```bash
export DWELLIR_API_KEY="YOUR_API_KEY"

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${DWELLIR_API_KEY}" \
  https://api-ethereum-mainnet.n.dwellir.com \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
```

The header also works with HTTP APIs that use paths after the endpoint host. This example calls the Hyperliquid Info API:

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${DWELLIR_API_KEY}" \
  https://api-hyperliquid-mainnet.n.dwellir.com/info \
  -d '{"type":"perpDexs"}'
```

### WebSocket

Send `X-Api-Key` during the WebSocket upgrade request. This Node.js example uses the `ws` package:

```javascript
import WebSocket from 'ws';

const ws = new WebSocket('wss://api-ethereum-mainnet.n.dwellir.com', {
  headers: {
    'X-Api-Key': process.env.DWELLIR_API_KEY,
  },
});
```

The browser WebSocket API cannot set custom headers. For production browser applications, connect through a backend that adds the header.

Direct URL path authentication exposes the key to every browser user. If you require direct browser access, create a separate key, set a strict quota, and rotate it when needed.

### gRPC

Send the API key as lowercase `x-api-key` request metadata:

```text
x-api-key: YOUR_API_KEY
```

See the [Sui gRPC authentication examples](https://www.dwellir.com/docs/sui/grpc-overview#authentication) for TypeScript, Python, and Go clients.

## URL path authentication

Add the API key after the endpoint host when your client cannot set custom headers:

```text
https://api-{network}.n.dwellir.com/YOUR_API_KEY
wss://api-{network}.n.dwellir.com/YOUR_API_KEY
```

Both forms use the same API key, quotas, and usage accounting.

Do not place a reusable server key in browser code. Browser users can read any key sent in the URL.

## Restrict a key by source IP

Authentication proves a request carries a valid key. It does not prove the request came from you. Add [IP whitelisting](https://www.dwellir.com/docs/getting-started/ip-whitelisting) so the key only works from source addresses you own.

Manage whitelists in the [IP Whitelisting tab](https://dashboard.dwellir.com/api-keys?tab=ip-whitelisting). A key with no enabled whitelist is unrestricted by IP. A restricted key denies everything else with HTTP 403 before the request reaches a node, so blocked traffic costs nothing.

Whitelisting suits server-side workloads with stable egress addresses. It cannot restrict browser or mobile clients. See [When to use IP whitelisting](https://www.dwellir.com/guides/when-to-use-ip-whitelisting) for that split.

## Protect the key in telemetry

Header authentication prevents the API key from appearing in the request URL. It does not hide the key from tools that record request headers.

Configure your logs, traces, reverse proxies, and error reports to redact `X-Api-Key`. Store the key in an environment variable or secret manager. Do not commit it to source control.