Authentication

Most OpenData endpoints are publicly accessible without authentication. API keys are required for higher rate limits and write operations.

Public Access

All read endpoints (GET requests) are available without authentication:

Dataset browsing and querying
Provider listings
Search functionality
Metadata access

Request

curl "https://api.tryopendata.ai/v1/datasets"

API Keys

API keys are required for:

Higher rate limits (see Rate Limits)
Dataset ingestion (POST /v1/datasets)
Dataset discovery (POST /v1/discoveries)
Usage analytics

Getting an API Key

Sign in to your OpenData account
Go to Settings
Click "Create API Key"
Copy and securely store your key

Security Warning

Never expose your API key in client-side code or public repositories. Store it securely in environment variables.

Using Your API Key

Your API key will look like od_live_abc123.... You can send it in either of two headers:

Option 1: Authorization header (Bearer token)

curl -H "Authorization: Bearer od_live_abc123..." \
  "https://api.tryopendata.ai/v1/datasets"

Option 2: X-API-Key header

curl -H "X-API-Key: od_live_abc123..." \
  "https://api.tryopendata.ai/v1/datasets"

Both formats are equivalent. Use whichever fits your HTTP client best. The X-API-Key header only accepts keys with the od_live_ prefix.

In Python:

import requests

# Bearer token
response = requests.get(
    "https://api.tryopendata.ai/v1/datasets",
    headers={"Authorization": "Bearer od_live_abc123..."}
)

# Or X-API-Key
response = requests.get(
    "https://api.tryopendata.ai/v1/datasets",
    headers={"X-API-Key": "od_live_abc123..."}
)

Error Responses

401 Unauthorized

Returned when authentication is required but not provided:

{
  "detail": "API key required for this operation"
}

403 Forbidden

Returned when the API key lacks permission for the operation:

{
  "detail": "API key does not have permission for this operation"
}

Best Practices

Rotate keys regularly - Create new keys periodically and revoke old ones
Use environment variables - Never hardcode keys in source code
Review your keys regularly - Check your API keys in Settings and revoke any you're no longer using