Skip to main content

​
Overview

All API requests must include your API key in the x-api-key HTTP header. Keys are issued from your Blockworks Research account and are tied to your organization/plan.
TopicTL;DR
Headerx-api-key: YOUR_API_KEY
Where to get itBlockworks Research → User Dropdown → Account Management → API
ScopeWorks across all documented endpoints unless noted otherwise
RotationCreate a new key, update your services, then revoke the old key
ErrorsMissing/invalid → 401 Unauthorized, insufficient access → 403 Forbidden

​
Quick start

curl -H "x-api-key: YOUR_API_KEY"   "https://api.blockworks.com/v1/metrics?project=ethereum&limit=1"

​
Sending the header

  • Always send x-api-key on every request.
  • Use HTTPS only.
  • Prefer environment variables or a secure secrets manager; never hardcode keys in code or commit history.

​
Example with Axios (Node)

import axios from "axios"

const api = axios.create({
  baseURL: "https://api.blockworks.com",
  headers: { "x-api-key": "YOUR_API_KEY" },
  timeout: 30_000
})

const { data } = await api.get("/v1/assets", { params: { limit: 20 } })

​
Key management best practices

  • Least privilege (if you use multiple keys per environment/team, give the narrowest access).
  • Separate keys per environment: dev, staging, prod.
  • Rotate regularly and on any suspected exposure. Safe rotation flow:
    1. Create a new key.
    2. Deploy config with the new key.
    3. Verify traffic and logs.
    4. Revoke the old key.
  • Store securely: cloud secrets manager (e.g., AWS Secrets Manager, GCP Secret Manager, 1Password) or your CI/CD secret store.
  • Audit usage from your account dashboard (failed requests, rate-limit spikes, unusual origins).

​
Common errors

StatusTypeWhy it happensHow to fix
401 Unauthorizedmissing_api_keyHeader not present or malformedAdd x-api-key with a valid key
401 Unauthorizedinvalid_api_keyUnknown or revoked keyUse an active key or rotate
403 Forbiddeninsufficient_scopeKey lacks access to the requested resourceRequest access or use a key with the right plan/scope
429 Too Many Requestsrate_limitedExceeded your plan limitsBackoff/retry with jitter, consider higher tier
5xxinternal_errorTransient service issueRetry with exponential backoff and idempotency where applicable

​
Error body shape

{
    "message": "Unauthorized",
    "statusCode": 401
}

​
Security checklist

  • Do not embed keys in client-side apps (browsers, mobile). Proxy through your backend.
  • Restrict egress on your servers if possible (allowlist api.blockworks.com).
  • Add rate limiting and retries with jitter to your client.
  • Log request_id from responses for support/debugging.
  • Consider key per service (ingesters, web, batch) to isolate exposure.

​
FAQ

Can I use multiple keys? Yes. Many teams keep separate keys per environment or workload. Api keys for the Blockworks API are team-scoped. Each user on your team will be able to generate and remove keys. Usage is aggregated across all keys on your team. Where do I find or revoke keys? In your blockworks research settings under API Keys.