Skip to main content
Every request to the REST API and the MCP endpoint requires a partner API key in the Authorization header: 
Authorization: Bearer whk_your_key_here
Keys look like whk_ followed by 48 hex characters. Whistle stores only a hash of your key — it can never be shown to you again after issuance.

​
Getting a key

Keys are issued by the Whistle team: email tommy@huddleup-sports.com with your integration’s name. There is no self-service key portal yet. The plaintext key is delivered once.

​
What your key can access

Partner keys are scoped principals, bound to a source namespace (e.g. "huddleup") when minted:
  • You can read and mutate only leagues whose source matches your key, plus any leagues explicitly granted to your key by the Whistle team.
  • Rows you create are stamped with your key’s source automatically — you may omit source from request bodies, or echo your own value. Sending any other value returns 400 {"error":"source_mismatch"}; identity can’t be spoofed via the body.
  • Webhook endpoints are owned by your source too: you list, delete, and read deliveries only for your own endpoints, and you receive events only for leagues in your scope.
Out-of-scope looks like nonexistent — by design. A league, game, or webhook endpoint outside your scope returns the exact same 404 and error code as one that doesn’t exist (league_not_found, game_not_found, endpoint_not_found). You cannot distinguish “not yours” from “not there”, so don’t treat a 404 as proof a resource is absent — only that it’s not accessible to you.

​
Failure behavior

Any authentication failure — missing header, malformed header, revoked or unknown key — returns the same response: status 401 with body 
{"error": "unauthorized"}
The API never returns 403 (authorization failures surface as the 404s described above). A 401 on a previously working integration almost always means the key was revoked or the header is no longer being sent — it is not retriable; fix the credential.

​
Handling your key safely

  • Store the key in a secret manager or environment variable (WHISTLE_API_KEY in these docs’ examples). Never commit it, log it, or embed it in client-side code.
  • The API is server-to-server only (no CORS), so there is never a legitimate reason for the key to reach a browser or mobile app.
  • Even though keys are source-scoped, a leaked key can still read and rewrite everything in your namespace — including reopening claimed positions and deleting your webhooks. Give each integration its own key so one can be revoked without breaking the others.

​
Rotation and revocation

There is no rotation endpoint. To rotate: request a new key from tommy@huddleup-sports.com, deploy it, then ask for the old key to be revoked. Revocation takes effect immediately — subsequent requests get 401. If you suspect a key has leaked, email support immediately to revoke it.

​
Verifying your key

The cheapest authenticated call is the API index: 
curl -s https://whistle.huddleup-sports.com/api/v1 \
  -H "Authorization: Bearer $WHISTLE_API_KEY"
A 200 with {"data":{"version":"v1", …}} means the key works. See the REST quickstart.
Last modified on July 10, 2026