Authentication¶

The Gnosis Analytics API uses header-based API key authentication with a tiered access control system. Higher-tier keys inherit access to all endpoints at or below their tier level, and public (tier0) endpoints can be called without any authentication.

How It Works¶

Every API request is evaluated through a two-step process:

1. Key validation -- The X-API-Key header is checked against the server's key registry. Invalid keys are rejected immediately with a 403 error.
2. Tier check -- The user's tier is compared against the endpoint's required tier. If the user's tier is lower than required, the request is denied.

For tier0 endpoints, both steps are relaxed: no key is required, and anonymous users are granted tier0 access by default.

The X-API-Key Header¶

Include your API key in the X-API-Key HTTP header on every request to non-public endpoints:

curl "https://api.analytics.gnosis.io/v1/consensus/blob_commitments/daily" \
  -H "accept: application/json" \
  -H "X-API-Key: YOUR_API_KEY"

Obtaining an API Key¶

API keys follow the format sk_live_<identifier>. Each key is associated with:

• A user name (for logging and audit)
• An organization name
• A tier level that determines access and rate limits

Access Tier Hierarchy¶

The tier system is hierarchical: a key at tier N can access all endpoints requiring tier N or below. A tier2 key, for example, has access to tier0, tier1, and tier2 endpoints.

graph LR
    T3[tier3 - Internal] -->|includes| T2[tier2 - Premium]
    T2 -->|includes| T1[tier1 - Partner]
    T1 -->|includes| T0[tier0 - Public]

Tier0: Public Endpoints¶

Endpoints tagged as tier0 are publicly accessible and do not require an API key. You can call them with no authentication header at all:

curl "https://api.analytics.gnosis.io/v1/consensus/blob_commitments/latest" \
  -H "accept: application/json"

When a valid API key is provided on a tier0 endpoint, the rate limit is keyed by that API key rather than the client's IP address. This gives authenticated users their own rate-limit bucket on public endpoints.

Example Requests by Tier¶

curl -s "https://api.analytics.gnosis.io/v1/consensus/blob_commitments/latest" \
  -H "accept: application/json"

curl -s "https://api.analytics.gnosis.io/v1/consensus/blob_commitments/daily" \
  -H "accept: application/json" \
  -H "X-API-Key: sk_live_partner_key"

curl -s "https://api.analytics.gnosis.io/v1/execution/token_balances/daily?symbol=GNO&limit=100" \
  -H "accept: application/json" \
  -H "X-API-Key: sk_live_premium_key"

curl -s -X POST "https://api.analytics.gnosis.io/v1/execution/token_balances/daily" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_internal_key" \
  -d '{
    "symbol": "GNO",
    "address": ["0xabc", "0xdef"],
    "start_date": "2024-01-01",
    "end_date": "2024-06-30",
    "limit": 1000
  }'

Using API Keys in Code¶

import requests

API_KEY = "sk_live_your_key_here"
BASE_URL = "https://api.analytics.gnosis.io/v1"

response = requests.get(
    f"{BASE_URL}/consensus/blob_commitments/daily",
    headers={
        "accept": "application/json",
        "X-API-Key": API_KEY,
    },
    params={"start_date": "2024-01-01", "limit": 100},
)

data = response.json()

const API_KEY = "sk_live_your_key_here";
const BASE_URL = "https://api.analytics.gnosis.io/v1";

const response = await fetch(
  `${BASE_URL}/consensus/blob_commitments/daily?start_date=2024-01-01&limit=100`,
  {
    headers: {
      "accept": "application/json",
      "X-API-Key": API_KEY,
    },
  }
);

const data = await response.json();

curl -s "https://api.analytics.gnosis.io/v1/consensus/blob_commitments/daily?start_date=2024-01-01&limit=100" \
  -H "accept: application/json" \
  -H "X-API-Key: sk_live_your_key_here"

Authentication Error Responses¶

All authentication failures return HTTP 403 Forbidden with a JSON body containing a detail field.

Missing API Key¶

Returned when a non-public endpoint (tier1+) is called without the X-API-Key header:

{
  "detail": "Missing authentication header: X-API-Key"
}

Invalid API Key¶

Returned when the provided key does not exist in the server's key registry. This applies to all endpoints, including tier0:

{
  "detail": "Invalid API Key"
}

Insufficient Tier Access¶

Returned when the key's tier is lower than the endpoint's required tier. The message includes both the required tier and the user's actual tier for debugging:

{
  "detail": "Access denied. This endpoint requires tier2 access. User 'bob' has tier1 access."
}

Security Best Practices¶

• Never embed API keys in client-side code (browser JavaScript, mobile apps). Use a backend proxy to keep your key server-side.
• Do not commit keys to version control. Use environment variables or a secrets manager.
• Use the minimum tier needed. If your application only reads public data, there is no need for a higher-tier key.
• Rotate keys periodically. If you suspect a key has been compromised, request a replacement from the Gnosis Analytics team.
• One key per application. Do not share keys across unrelated services -- this makes it easier to track usage and revoke access if needed.

Next Steps¶

• Endpoints -- Understand the URL structure and available data categories.
• Rate Limits -- Learn about per-tier rate limits and how to handle throttling.
• Error Handling -- Full reference of all error codes and response formats.