// Handball API authentication
Sending your key in either of two headers, why never in the address, and rotating a key.
Send your key in one of two headers. Both work on every endpoint and on the MCP server.
Authorization: Bearer YOUR_KEY
curl -H "Authorization: Bearer YOUR_KEY" https://api.handballapi.com/v1/results/yesterdayX-API-Key: YOUR_KEY
curl -H "X-API-Key: YOUR_KEY" https://api.handballapi.com/v1/results/yesterdayA key in the address (?api_key=, ?key=) is refused with 400 bad_request, so keys never end up in logs or browser history. A missing, unknown or revoked key is 401 unauthorized.
Your plan is read from your account on every call, so an upgrade works on your next request with the same key.
Rotating a key
Make a new key in your account under Keys, move your app over to it, then revoke the old one. A revoked key stops at once with 401 unauthorized. All your keys share your plan's limits, and each call is counted against the key that made it, so you can see which app is busy.
The key you make in your account is saved for these documentation pages in your own browser, so Try it works with it straight away.
GET /v1/usage tells a key about itself: plan, calls today and this month, the limits, when they reset and how far back its results reach. It is never counted against your allowance.