Authentication

The API has two authentication models:

API keys, sent in the x-statmuse-api-key header, authenticate REST requests (/sports/...) and server-to-server MCP callers.
OAuth sign-in authenticates interactive MCP clients (/mcp). You sign in with your statmuse.com account when connecting a client, and no API key is involved.

Both resolve to the same account: one plan, one quota, shared across REST and MCP.

API keys (REST)

Every request to the sports endpoints (/sports/...) must include an API key in the x-statmuse-api-key header.

curl "https://api.statmuse.com/sports/mlb/v1/ask?input=who+leads+the+AL+in+OPS" \
  -H "x-statmuse-api-key: $STATMUSE_API_KEY"

Key format

Keys are 32-byte URL-safe random strings (~43 characters). Treat keys like passwords: never commit them to source control, never ship them in client code and never log them.

Multiple keys, rotation and revocation

An account can hold several active keys at once, up to a per-account limit (the dashboard shows yours). Each key authenticates independently and can be revoked independently, which enables two practices worth adopting:

Zero-downtime rotation. Create a new key, roll it into your secret store, deploy, then revoke the old key once nothing uses it. Both keys work during the transition, so there is no window of failed requests.
One key per app or environment. Give each application, environment or integration its own key. If one leaks or is retired, revoke just that key and everything else keeps running.

A revoked key stops authenticating immediately and fails with auth-key-disabled.

Failure modes

Status	Slug	Cause
401	`auth-key-missing`	No `x-statmuse-api-key` header on the request.
401	`auth-key-invalid`	Header present but doesn’t match a known key (or is longer than 256 characters).
403	`auth-key-disabled`	Key was revoked from the dashboard.
403	`account-disabled`	Account is disabled. Contact support if this is unexpected.

All errors return problem-details JSON.

Server-side only

Call the API from your backend. The sports endpoints accept cross-origin browser requests only from the StatMuse API Portal (so the API Reference’s try-it console works). Requests from any other page are blocked by the browser’s same-origin policy. More importantly, a key shipped in client code lets any visitor consume your quota. Proxy through your own server.

Interactive MCP clients don’t use API keys. Their connector UIs have nowhere to paste one. When you connect a client, it walks through an OAuth sign-in: a browser window opens, you sign in with your statmuse.com account and approve the access, and the client receives its own token. You never handle a secret yourself. Connect your agent has step-by-step setup per client. (Headless callers with no human to sign in are the exception: they authenticate with an API key; see Server-to-server access.)

Each client you authorize appears as a connected agent on the portal’s Connected agents page. Disconnecting one revokes its access immediately and independently, the MCP counterpart to revoking an API key.