Bitquery Authentication: API Key Setup and Security (2026)

Authentication overview

Bitquery utilizes API keys as its primary method for authenticating access to its suite of blockchain data APIs, including the GraphQL and Streaming APIs. An API key is a unique token that identifies the calling application or user, authenticating their requests and associating them with a specific Bitquery account. This system allows Bitquery to manage access, monitor usage against plan limits, and apply appropriate permissions to the requested data. The API key must be included with every API request to successfully query blockchain data from networks such as Ethereum, Polygon, and Avalanche.

The use of API keys is a common practice for authenticating access to web services, offering a balance between security and ease of implementation for developers. While simpler than token-based authentication methods like OAuth 2.0, API keys still require careful handling to prevent unauthorized access. Best practices for securing API keys are critical to maintaining the integrity of your applications and data.

Supported authentication methods

Bitquery primarily supports API key authentication for accessing its GraphQL and Streaming APIs. This method involves generating a unique API key from the Bitquery console and including it in the HTTP headers of your requests.

API Key (Header) Authentication

For Bitquery, the API key is typically passed in a custom HTTP header named X-API-KEY. This method ensures that the key is transmitted securely over HTTPS, separating it from the URL parameters or request body, which could be more susceptible to logging or exposure. Using a custom header is a standard way to implement API key authentication, as described in general API security guidelines by providers like Cloudflare's API documentation.

Getting your credentials

To obtain your Bitquery API key, you need to create an account on the Bitquery platform and access your developer console. The process involves a few steps:

1. Sign up or Log in: Navigate to the Bitquery homepage and either sign up for a new account or log in to an existing one. New users typically start with the Developer Plan, which includes a free tier of 50,000 credits per month.
2. Access the Console: Once logged in, go to your Bitquery console or dashboard. This is usually accessible via a "Dashboard" or "API Keys" link in your account's navigation.
3. Generate API Key: Within the console, locate the section for API keys. There should be an option to "Generate New Key" or "Create API Key." Bitquery allows you to create multiple keys, which is a good practice for different projects or environments (e.g., development, staging, production). For detailed steps, refer to the Bitquery official documentation.
4. Copy Your API Key: After generation, your unique API key will be displayed. It's crucial to copy this key immediately and store it securely, as it may not be retrievable again for security reasons (only regenerated).

Each API key is tied to your account and plan, determining the rate limits and access permissions you have. You can manage your API keys, including revoking old keys and generating new ones, directly from the Bitquery console.

Authenticated request example

When making requests to the Bitquery GraphQL API, your API key must be included in the X-API-KEY header. Below are examples using cURL and JavaScript, which are common for interacting with GraphQL APIs. The GraphQL endpoint for Bitquery is https://graphql.bitquery.io/.

cURL Example

This cURL example demonstrates a simple GraphQL query to fetch the latest blocks, including the API key in the header:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_BITQUERY_API_KEY" \
  --data-binary '{"query":"query { ethereum { blocks { blockHash blockNumber } } }"}' \
  https://graphql.bitquery.io/

Replace YOUR_BITQUERY_API_KEY with your actual API key obtained from the Bitquery console.

JavaScript Example (using fetch API)

For client-side or Node.js applications, you can use the fetch API or a GraphQL client library. This example uses fetch:

const BITQUERY_API_KEY = 'YOUR_BITQUERY_API_KEY';
const GRAPHQL_ENDPOINT = 'https://graphql.bitquery.io/';

async function fetchBitqueryData() {
  const query = `
    query {
      ethereum {
        blocks(limit: 1, orderBy: blockNumber_DESC) {
          blockHash
          blockNumber
          timestamp
        }
      }
    }
  `;

  try {
    const response = await fetch(GRAPHQL_ENDPOINT, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-KEY': BITQUERY_API_KEY,
      },
      body: JSON.stringify({ query }),
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Bitquery Data:', data);
  } catch (error) {
    console.error('Error fetching Bitquery data:', error);
  }
}

fetchBitqueryData();

Again, replace YOUR_BITQUERY_API_KEY with your key. For more complex applications, consider using a dedicated GraphQL client like Apollo Client or Relay, which can simplify query management and integration.

Security best practices

Securing your Bitquery API key is crucial to prevent unauthorized access to your account and data. Adhering to general API key security principles, as outlined by resources such as Google's API security recommendations, helps protect your credentials.

1. Keep API Keys Confidential

• Do not embed directly in client-side code: For web applications running in a browser, direct embedding of API keys in JavaScript can expose them to anyone inspecting your page's source code. If client-side access is necessary, consider using a proxy server to append the API key or implement domain restrictions.
• Store securely: On server-side applications, store API keys in environment variables, secret management services (e.g., AWS Secrets Manager, Google Secret Manager), or configuration files that are not committed to version control.
• Avoid public repositories: Never hardcode API keys directly into your source code, especially if it's hosted in public repositories like GitHub. Use .gitignore to exclude configuration files containing keys.

2. Restrict API Key Usage

• IP Whitelisting: If your API calls originate from a fixed set of server IPs, configure IP restrictions for your API keys in the Bitquery console. This ensures that only requests from specified IP addresses are honored.
• Domain/Referrer Restrictions: For web applications, configure domain or referrer restrictions to limit key usage to your authorized domains. This is particularly useful for keys that must be exposed client-side.
• Least Privilege: Generate separate API keys for different applications or environments (development, staging, production). This limits the blast radius if one key is compromised. Revoke any unused or old keys.

3. Monitor and Rotate Keys

• Monitor usage: Regularly check your Bitquery account's API usage dashboard for unusual activity. Spikes in usage or unexpected queries could indicate a compromised key.
• Key rotation: Periodically rotate your API keys. This involves generating a new key, updating your applications to use the new key, and then revoking the old one. A common practice is to rotate keys every 90 days or annually, similar to password rotation policies.
• Implement logging: Maintain logs of API access and key usage within your applications to aid in auditing and incident response.

4. Use HTTPS

• Always ensure that all API requests to Bitquery are made over HTTPS. This encrypts the communication channel, protecting your API key and data from eavesdropping during transit. Bitquery's GraphQL endpoint (https://graphql.bitquery.io/) enforces HTTPS by default.

By implementing these best practices, you can significantly enhance the security posture of your Bitquery integration and protect your blockchain data access.