Authentication

Forecast should expose one external auth story even though the current internals use multiple mechanisms.

Recommended external contract

Market Data Key
User Token

Use API keys for public, paid, and trial market-data access.

Example header

curl --header 'Authorization: Bearer YOUR_API_KEY' \
  'https://api.forecast.example/api/v1/markets?view=matched'

await fetch('https://api.forecast.example/api/v1/markets?view=matched', {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY'
  }
});

requests.get(
    "https://api.forecast.example/api/v1/markets",
    params={"view": "matched"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)

Internal reality today

The current stack already uses:

Supabase JWTs for user-scoped product routes
engine admin secrets for server-to-server proxying
service credentials for lake and infrastructure access

That is acceptable internally, but public docs should not mirror that complexity.

Recommendation

Standardize the external contract to:

one API key pattern for data products
one user-token pattern for workspace APIs

Keep engine secrets and infrastructure credentials out of customer documentation entirely.

​Authentication

​Recommended external contract

​Example header

​Internal reality today

​Recommendation

Authentication

Recommended external contract

Example header

Internal reality today

Recommendation