Authentication

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 Portal at app.blockdaemon.com:

• API Suite keys and Staking keys are managed on separate pages in the Portal.
• Staking key limits are static.
• Each API Suite key can be configured with unique limits, but the default/max is tied to your API subscription.

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

• Staking products → Staking Authentication page
• API Suite products → API Suite Authentication page

Staking access blocked unexpectedly? Contact Blockdaemon Support to confirm.

Supported Methods

Blockdaemon APIs support the following authentication methods:

❗️

Important Note

Never expose your API keys or access tokens in client-side applications or to anyone.

Generate and manage your API keys from the Portal.

1. Bearer Token

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 -X POST -H 'Content-Type: application/json' 'YOUR_ENDPOINT_URL/tendermint_rest/status?auth=YOUR_API_KEY'

3. API Key in Header

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 with ephemeral tokens. Upload your public key in the Portal on the authentication page under JWT heading, then generate a JWT with your private key.

Setup

1. Navigate to the API Suite Authentication page in the Portal.
2. Upload your public key.
3. After upload, a subject string is provided.
4. Set the subject string as the subject field in the generated JWT.

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 Portal and edit the key you want to restrict.

Limit types

📘

Note

Quota breach notification emails are not sent when a key-level limit is reached. Notifications are reserved for subscription-level quota events.

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 Portal.

Restriction types

Base URLs

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

👍

Note

See the Supported Chains page for a full list of available chains and networks.

Sample Responses

Successful Response

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

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'

Results are returned in wei denomination and NDJSON format.

{
  "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.

{
  "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)
• If using a browser or tool that caches credentials, clear the cache or restart the session.

🚧

Note

Still having trouble? Reach out to Blockdaemon Support.