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

# Authorization

> API keys, the BlockDB dashboard, and how to send credentials on every request.

## Overview

BlockDB authenticates **REST** and **WebSocket** traffic with **API keys**. Send your key in the `Authorization` header on every request that requires authentication. Keys are tied to your subscription: which datasets and chains you can query, your [compute unit](/api-reference/overview/compute-units) allowance, and your [rate limit](/api-reference/overview/rate-limiting). See the [dataset index](/data-catalog/evm/dataset-index) and [Dataset ID](/api-reference/enumerations/dataset-id) for how products map to `blockdb_evm` tables.

<Info>
  There is **no separate token endpoint** and **no OAuth flow**. The string you copy from the dashboard is the credential you pass as `Bearer <key>`.
</Info>

## Get an account and API keys

<Steps>
  <Step title="Open an account">
    Sign up at [accounts.blockdb.io](https://accounts.blockdb.io/sign-up) if you do not already have a BlockDB account.
  </Step>

  <Step title="Create and manage keys in the dashboard">
    Open **[dashboard.blockdb.io](https://dashboard.blockdb.io)**. There you can:

    * **Create** new API keys (up to **5 active keys** per account)
    * **Label** keys (for example production vs staging)
    * **Rotate** a key when you need a new secret while phasing out an old one
    * **Revoke** a key that is compromised or no longer needed

    Store keys only in environment variables or a secret manager—never commit them to source control.
  </Step>

  <Step title="Send the key on each request">
    Use the HTTP `Authorization` header with the `Bearer` scheme:

    ```
    Authorization: Bearer <your_api_key>
    ```
  </Step>
</Steps>

## Code examples: call the API with an API key

Set **`BLOCKDB_API_KEY`** in your environment (or substitute the value from the dashboard). These examples use the historic REST base URL **`https://api.blockdb.io/v1`**.

<CodeGroup>
  ```bash cURL theme={null}
  # Usage (no body)
  curl -sS "https://api.blockdb.io/v1/usage" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY"

  # Example data request
  curl -sS -X POST "https://api.blockdb.io/v1/evm/raw/blocks" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"chain_id":1,"from_block":12345678,"to_block":12345999,"limit":10}'
  ```

  ```python Python theme={null}
  import os
  import requests

  API_BASE = "https://api.blockdb.io/v1"
  KEY = os.environ["BLOCKDB_API_KEY"]

  h = {"Authorization": f"Bearer {KEY}"}

  r = requests.get(f"{API_BASE}/usage", headers=h, timeout=30)
  r.raise_for_status()
  print(r.json())

  r2 = requests.post(
      f"{API_BASE}/evm/raw/blocks",
      headers={**h, "Content-Type": "application/json"},
      json={"chain_id": 1, "from_block": 12345678, "to_block": 12345999, "limit": 10},
      timeout=30,
  )
  r2.raise_for_status()
  print(r2.json())
  ```

  ```javascript Node.js theme={null}
  const API_BASE = "https://api.blockdb.io/v1";
  const key = process.env.BLOCKDB_API_KEY;
  if (!key) throw new Error("Set BLOCKDB_API_KEY");

  const headers = { Authorization: `Bearer ${key}` };

  const usage = await fetch(`${API_BASE}/usage`, { headers });
  console.log(await usage.json());

  const blocks = await fetch(`${API_BASE}/evm/raw/blocks`, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      chain_id: 1,
      from_block: 12345678,
      to_block: 12345999,
      limit: 10,
    }),
  });
  console.log(await blocks.json());
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;

  var key = Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")
      ?? throw new InvalidOperationException("Set BLOCKDB_API_KEY");

  using var http = new HttpClient { BaseAddress = new Uri("https://api.blockdb.io/v1/") };
  http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", key);

  var usage = await http.GetAsync("usage");
  usage.EnsureSuccessStatusCode();
  Console.WriteLine(await usage.Content.ReadAsStringAsync());

  var body = new StringContent(
      """{"chain_id":1,"from_block":12345678,"to_block":12345999,"limit":10}""",
      Encoding.UTF8,
      "application/json");
  var blocks = await http.PostAsync("evm/raw/blocks", body);
  blocks.EnsureSuccessStatusCode();
  Console.WriteLine(await blocks.Content.ReadAsStringAsync());
  ```
</CodeGroup>

### Official SDKs

The [.NET](/api-reference/sdks/dotnet), [Python](/api-reference/sdks/python), and [JavaScript](/api-reference/sdks/javascript) SDKs accept your API key and attach `Authorization: Bearer` for you. See each SDK page for the exact constructor and configuration options.

## Security practices

* **Rotation:** Create a new key in the dashboard, deploy it, then revoke the old key.
* **Least privilege:** Use separate keys for production and non-production when possible (within the five-key limit).
* **Incidents:** Revoke a key immediately if it leaks; create a replacement in the dashboard.

## See Also

* [Usage & Limits](/api-reference/account-and-usage/usage) — `plan`, `cu_*`, and `rate_limit_rps` for your key
* [Rate Limiting](/api-reference/overview/rate-limiting) — RPS, backoff, and `429` handling
* [Error Codes](/api-reference/overview/error-codes) — Full error reference
* [Troubleshooting: API Authentication Failures](/troubleshooting/runbooks/api-authentication-failures) — 401/403 runbook

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.blockdb.io/v1/evm/raw/blocks' \
    -H 'Authorization: Bearer <BLOCKDB_API_KEY>' \
    -H 'Content-Type: application/json' \
    -d '{
      "chain_id": 1,
      "from_block": 12345678,
      "to_block": 12345999
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "meta": {
      "chain_id": 1,
      "request_window": {
        "from_block": 12345678,
        "to_block": 12345999
      },
      "filters": {
        "limit": 10,
        "cursor": null
      }
    },
    "data": [],
    "cursor": null,
    "page_count": 0
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "The request contains invalid or missing parameters.",
      "hint": "Validate all required parameters against the endpoint specification before retrying.",
      "severity": "error",
      "retryable": false,
      "details": {
        "invalid_parameters": [
          {
            "name": "chain_id",
            "location": "query",
            "reason": "missing",
            "expected": "positive integer, e.g. 1"
          },
          {
            "name": "from_timestamp",
            "location": "query",
            "reason": "invalid_format",
            "expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
          }
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/home"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
      "severity": "error",
      "retryable": false,
      "details": {
        "auth_scheme": "bearer",
        "expected_header": "Authorization: Bearer <API_KEY>",
        "provided_header": "Authorization: <REDACTED_OR_MISSING>",
        "token_status": "invalid_or_missing",
        "recommendation": "Regenerate the API key if you suspect it is expired or compromised."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "http_status": 403,
      "message": "Your API key does not have permission to access this endpoint.",
      "hint": "Upgrade your subscription tier or request additional access.",
      "severity": "warning",
      "retryable": false,
      "details": {
        "required_plan": "production",
        "your_plan": null,
        "contact": "support@blockdb.io",
        "recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "The requested resource does not exist.",
      "hint": "Verify the API endpoint",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 413 theme={null}
  {
    "error": {
      "code": "PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "message": "The requested response exceeds the maximum allowed size of 10 MB.",
      "hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
      "details": {
        "max_allowed_bytes": 10485760,
        "estimated_response_bytes": 15360000,
        "recommended_actions": [
          "Decrease the 'limit' parameter value",
          "Shorten the block range or time window",
          "Filter by fewer pools or exchanges"
        ]
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "CHAIN_NOT_SUPPORTED",
      "http_status": 422,
      "message": "chain_id=137 is not supported.",
      "hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "http_status": 429,
      "message": "You have exceeded the allowed request rate.",
      "hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
      "details": {
        "limit_rps": 1000,
        "current_estimated_rps": 73,
        "retry_after_seconds": 2,
        "limit_scope": "api_key",
        "limit_window_seconds": 1
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "hint": "This error is not caused by your request. You may retry after a short delay.",
      "severity": "critical",
      "retryable": true,
      "details": {
        "incident_id": "INC-2025-11-11-123456",
        "temporary_issue": true,
        "expected_recovery_seconds": 5
      },
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>