Permissions & scopes
What an API key or MCP OAuth grant is allowed to do, and how to request the least access you need.
Keys are read-only
The statshawk REST API is a read-only data surface. An API key can read stats; it can never create, modify, or delete data, change your plan, rotate other keys, or touch your account settings. Account management happens only in the dashboard behind a browser login. It is not reachable with an API key at all.
That means the blast radius of a leaked key is bounded to reading data and consuming your
quota. Revoke it in the dashboard and the next request receives 401.
Key environments
| Prefix | Scope | Intended use |
|---|---|---|
sk_live_… | Read all data, metered against your plan | Production traffic |
sk_test_… | Read all data, metered against your plan, attributed separately | Staging, CI, agent experiments |
Both environments authenticate identically; the split exists so you can rotate and audit the two traffic classes independently (see Authentication). Create one key per integration or per agent so you can revoke a single consumer without disturbing the rest.
Plan tier as an access scope
Some endpoints require a paid plan. A Free-tier key calling one of them receives
403 TIER_REQUIRES_PAID rather than partial data, so an agent can detect the boundary
deterministically. Per-competition feature support is discoverable up front via
GET /v1/competitions/{comp}/capabilities and GET /v1/persons/{person_id}/capabilities.
MCP OAuth scopes
The MCP server at https://mcp.statshawk.ai/mcp uses OAuth 2.1 with PKCE. The
authorization server metadata is published at
/.well-known/oauth-authorization-server and the
resource metadata at https://mcp.statshawk.ai/.well-known/oauth-protected-resource.
| Scope | Grants |
|---|---|
stats:read | get_standings, get_box_score, search_games, get_team_roster, get_play_by_play, search_player, get_odds_markets, get_odds_spot, get_odds_history |
analysis:read | get_mlb_matchups, get_player_props |
Both scopes are read-only; a token never grants account or billing access. Assistants
request both by default. Request only stats:read if an agent does not need the analysis
tools. Revoke a connected assistant from the dashboard at any time.
Requesting least privilege
- Agents: use a
sk_test_…key named after the agent, or the MCP OAuth flow, never a shared production key. - Products: one
sk_live_…key per service; rotate on a schedule via the dashboard. - CI: a
sk_test_…key stored as a secret; revoke when the pipeline is retired.