Each API product in Blockdaemon serves a specific purpose, from querying blockchain data to managing staking and interacting with DeFi protocols. To use them, you need to authenticate the request with a valid API key or token.

### API Suite Keys vs. Staking Keys

Blockdaemon manages two distinct key types, each with their own page in the WebApp at [app.blockdaemon.com](https://app.blockdaemon.com/):

- **API Suite keys** and **Staking keys** are managed on **separate pages** in the WebApp.
- Increasing your API Suite subscription does **not** raise RPS limits on Staking keys.
- Reaching your API Suite quota does **not** block dedicated Staking-only keys, and vice versa. A key that includes both API Suite and Staking products may have all access blocked if its API Suite quota is reached.
- Limits are enforced **per key**, not per product — each key has its own independent rate and compute-unit limits.

Keys only appear in the WebApp on the page that matches their product type:

- **Staking products** → Staking Authentication page
- **API Suite products** → API Suite Authentication page
- A key associated with both product types appears on both pages, scoped to the relevant products.

**Staking access blocked unexpectedly?** If a staking key appears blocked due to a quota error, one of two things has occurred: the key includes API Suite products that have reached their quota, or an org admin has revoked staking access for your organization. Contact your org admin or [Blockdaemon Support](mailto:support@blockdaemon.com) to confirm.

## Supported Methods

Blockdaemon APIs support the following authentication methods:

| Method | Usage |
| --- | --- |
| **Bearer Token** | `Authorization: Bearer YOUR_API_KEY` (often used with OAuth2) |
| **API Key (Query Parameter)** | Append `?apiKey=YOUR_API_KEY` to the endpoint URL |
| **API Key (Header)** | `X-API-Key: YOUR_API_KEY` |
| **JWT (Public Key Upload)** | Upload your public key in the WebApp; sign JWTs with your private key |

### 1. Bearer Token

```curl
curl --request POST \
     --url https://svc.blockdaemon.com/ethereum/mainnet/native/rpc \
     --header "Authorization: Bearer YOUR_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{
       "jsonrpc": "2.0",
       "method": "eth_blockNumber",
       "params": [],
       "id": 1
     }'
```

### 2. API Key as Query Parameter

```curl
curl -X POST -H 'Content-Type: application/json' 'YOUR_ENDPOINT_URL/tendermint_rest/status?auth=YOUR_API_KEY'
```

### 3. API Key in Header

```curl
curl --request GET \
     --url https://svc.blockdaemon.com/universal/v1/bitcoin/mainnet/sync/block_number \
     --header "X-API-Key: YOUR_API_KEY" \
     --header "Accept: application/json"
```

### 4. JWT Authentication

JWT authentication lets you authenticate without transmitting your API key directly. Upload your RSA or EC public key in the [WebApp](https://app.blockdaemon.com/), then sign your requests locally with your private key.

**Setup**

1. Navigate to the API Suite Authentication page in the [WebApp](https://app.blockdaemon.com/).
2. Upload your RSA or EC public key.
3. After upload, a **subject string** is provided — set this as the `sub` claim in all JWTs you sign.

**Requirements**

- Supported signing algorithms: **RS256** or **ES256** only.
- Maximum JWT expiry (`exp`): **24 hours** from the time of issuance.

## Key-Level Limits (API Suite)

API Suite keys support custom per-key compute-unit (CU) and requests-per-second (RPS) limits, set independently beneath your subscription ceiling. This lets you allocate separate quotas for development, staging, and production keys without consuming your full subscription budget in any single environment.

**How to configure**

Navigate to the API Suite Authentication page in the [WebApp](https://app.blockdaemon.com/) and edit the key you want to restrict.

**Limit types**

| Limit | Description |
| --- | --- |
| **Key RPS** | Maximum requests per second allowed for this key |
| **Key CU quota** | Maximum compute units this key can consume, beneath the subscription quota |

## Key-Level Allowlists

Both API Suite and Staking keys support allowlists that restrict which clients can use a given key. Configure allowlists from the relevant Authentication page in the [WebApp](https://app.blockdaemon.com/).

**Restriction types**

| Type | Description |
| --- | --- |
| **User Agent** | Allow requests only from clients matching a specified user agent string |
| **Domain** | Allow requests only from specified referring domains |
| **CIDR Range** | Allow requests only from IP addresses within specified CIDR blocks |

## Base URLs

Use the base URL that corresponds to the product you're working with:

| Product | Base URL |
| --- | --- |
| [RPC API](https://docs.blockdaemon.com/reference/rpc-api-overview) | `https://svc.blockdaemon.com/{protocol}/{network}/native/{connection_type}` |
| [Staking API](https://docs.blockdaemon.com/reference/staking-api-overview) | `https://svc.blockdaemon.com/boss/v1/{protocol}/{network}/{endpoint}` |
| [Staking Reporting API](https://docs.blockdaemon.com/reference/stakingreporting-api-overview) | `https://svc.blockdaemon.com/reporting/staking/v2/{protocol}/{network}/{endpoint}` |
| [Dedicated Nodes](https://docs.blockdaemon.com/docs/blockchain-nodes) | Depends on the connection type, learn more [here](https://docs.blockdaemon.com/docs/blockchain-nodes). |
| [DeFi API](https://docs.blockdaemon.com/docs/defi-api-overview) | `https://svc.blockdaemon.com/defi/v1/{modules}/{endpoint}` |
| [Token Price API](https://docs.blockdaemon.com/reference/introduction-token-price) | `https://svc.blockdaemon.com/pricing/v1/{endpoint}` |

## Sample Responses

### Successful Response

This request retrieves validator yield metrics for the Ethereum mainnet between a specific `startTime` and `endTime`.

Request

```curl
curl --request GET \
     --url 'https://svc.blockdaemon.com/reporting/staking/v2/ethereum/mainnet/validator/yield?startTime=1709251200&endTime=1711929600&denomination=wei&raw=false' \
     --header 'X-API-Key: YOUR_API_KEY' \
     --header 'accept: application/x-ndjson'
```

Response - OK

```json
{
  "startTime": 1709251200,
  "endTime": 1711929600,
  "return": "283291849202",
  "apr": "0.0601",
  "aprPercentage": "6.01%",
  "apy": "0.06912",
  "apyPercentage": "6.912%",
  "denomination": "ETH",
  "stake": "3830810096309000",
  "metadata": {
    "epoch": "285413-287302",
    "protocolRewards": "11.582442116",
    "mevRewards": "2.55849541422880986",
    "blockRewards": "1.660716278059616145",
    "totalBalance": "33750555.15182654"
  }
}
```

### Error: 401 Unauthorized

This error occurs when your request lacks valid authentication credentials.

JSON

```json
{
  "type": "unauthorized",
  "title": "Invalid Token",
  "status": 401
}
```

**❌ Common Causes**

- You're using a revoked or expired API key.
- You're using an API key from a different project or organization.
- Your API key doesn't have permissions to access this endpoint.
- A cached or outdated API key is still being used by your client or browser.

**⚙️ How to Resolve It**

- Verify your API key and make sure you're including it in one of the authentication methods.
- Check your project settings to ensure you use the correct key.
- Renew a new API key from your Blockdaemon dashboard if you're unsure whether your current key is valid (not applicable on a [free plan](https://docs.blockdaemon.com/docs/subscription-management))
- If using a browser or tool that caches credentials, clear the cache or restart the session.