API keys
Every call to /api/v2/* carries an API key. You create keys yourself from your account. This page covers how to send them, how to rotate them, and what to do if one leaks.
In plain words. A key is a private password for your own software: it tells Brubru who is calling. Trying the API in the API Console needs no key at all.
How to authenticate
Two header formats are accepted. Use whichever suits your tooling:
Option A: Authorization: Bearer (recommended)
This is the standard for most API tooling (Postman, curl, Python requests, fetch, axios, language SDKs). If you're not sure which to pick, use Bearer.
curl -H "Authorization: Bearer brubru_live_abc123..." \
"https://brubru-production.up.railway.app/api/v2/legislative/eur-lex/laws?limit=5"
Option B: X-API-Key header
A bit easier to type by hand in curl one-liners. Interchangeable with Bearer.
curl -H "X-API-Key: brubru_live_abc123..." \
"https://brubru-production.up.railway.app/api/v2/legislative/eur-lex/laws?limit=5"
If you send both, Bearer wins. The X-API-Key header is ignored in that case. So it's safe to leave one configured at the SDK level and occasionally override with the other.
Key format
Brubru API keys look like:
brubru_live_0123456789abcdef0123456789abcdef0123456789abcdef
That's the literal prefix brubru_live_ followed by 48 hexadecimal characters (192 bits of entropy). The prefix helps us and GitHub's secret-scanner find leaked keys automatically.
Getting a key
- Create a free account, or sign in.
- Open Your API keys and create a key. You can hold up to three active keys, each lasting 30, 90, 180 or 365 days. The key is shown once: copy it then.
- Add credit on the billing page. For pricing, write to hello@beresol.eu.
Rotation & revocation
To rotate a key (recommended at least once every 90 days, immediately after an incident):
- Create a new key under Your API keys.
- Update your secrets store (Railway variables, GitHub Actions secrets, AWS Secrets Manager, etc.) with the new key.
- Deploy. Validate with a ping.
- Revoke the old key from the same page.
If you believe a key has leaked, revoke it straight away. Keys are stored as hashes on our side; we never see your plaintext after issuing.
Access checks
At each request we verify:
- The key exists, is not revoked and has not expired.
- The owner's account is active.
- The key's scopes and bundles cover this route.
- The per-key rate limit has not been exceeded in the current 60-second window.
- The account's balance covers the call.
Any failure returns a structured 401/402/403/429: see Errors.
Storing the key safely
Never commit API keys to git. Use environment variables, secret managers, or platform-provided secret stores.
Good patterns:
# In .env (add .env to .gitignore)
BRUBRU_API_KEY=brubru_live_...
# In your code
import os
import httpx
r = httpx.get(
"https://brubru-production.up.railway.app/api/v2/legislative/eur-lex/laws",
headers={"Authorization": f"Bearer {os.environ['BRUBRU_API_KEY']}"},
)
If you absolutely must inline the key in client-side JavaScript (don't: proxy through your backend), scope it to read-only and rotate aggressively.
WWW-Authenticate challenge
401 responses include the WWW-Authenticate header:
WWW-Authenticate: Bearer realm="Brubru API"
This lets HTTP client libraries surface a friendly auth prompt (curl with --anyauth, browser fetch with credential prompts, etc.).
Examples
Python
import os
import httpx
BASE = "https://brubru.beresol.eu"
headers = {"Authorization": f"Bearer {os.environ['BRUBRU_API_KEY']}"}
r = httpx.get(f"{BASE}/api/v2/legislative/eur-lex/laws", params={"q": "GDPR", "limit": 3}, headers=headers)
r.raise_for_status()
print(r.json()["data"])
Node.js
const response = await fetch(
"https://brubru-production.up.railway.app/api/v2/legislative/eur-lex/laws?q=GDPR&limit=3",
{ headers: { Authorization: `Bearer ${process.env.BRUBRU_API_KEY}` } }
);
const body = await response.json();
console.log(body.data);
TypeScript (axios)
import axios from "axios";
const api = axios.create({
baseURL: "https://brubru.beresol.eu",
headers: { Authorization: `Bearer ${process.env.BRUBRU_API_KEY}` },
});
const { data } = await api.get("/api/v2/legislative/eur-lex/laws", { params: { q: "GDPR", limit: 3 } });
Next
Once you can make a 200 call, head to Response envelope to understand the shape every endpoint returns.