Skip to main content

​
API key vs. bearer token

the API uses HTTP Bearer auth, and the bearer token is your edgeful API key. if the API Reference authorization drawer asks for a “Bearer token”, paste the API key itself. do not include Bearer there; Mintlify adds it on the wire.

​
header format

  • Authorization: Bearer ef_live_<random> (single space between Bearer and the key, no colon).
  • sent on every request. no session, no cookie.
  • the Mintlify playground accepts the bare key (no need to type Bearer ).
example request — same shape as quickstart step 2: 
curl -H "Authorization: Bearer $EDGEFUL_API_KEY" \
  "https://api.edgeful.com/report_calculation/outside-days-standard/futures/SPY?start_date=2024-01-01&end_date=2024-12-31"

​
key format

  • keys start with the ef_live_ prefix.
  • plaintext is shown only once on creation.
  • lost keys cannot be recovered — delete it and generate a new one.
  • the dashboard shows a short display prefix so you can identify each key without exposing the full value.

​
plan access

your API key includes your plan. if a request is outside that plan, the API returns 403 Forbidden with a short code explaining which limit was hit.
  • Essential: starter reports and starter tickers, up to 6 months of history, no live data, no detailed rows.
    • starter reports: opening-stats-*, green-and-red-days-by-weekday-standard, and previous-days-range-*.
    • starter tickers: AAPL for stocks, RTY for futures, ETHUSDT for crypto, and GBPCAD for forex.
  • Pro: all report endpoints and supported tickers, up to 12 months of history, live data included, no detailed rows.
  • All Access: all report endpoints and supported tickers, up to 96 months of history, live data included, detailed rows included when available.
common 403 codes: missing_entitlement, report_not_allowed, ticker_not_allowed, history_range_exceeded, and live_data_not_allowed.

​
error responses

  • 401 Unauthorized — missing, malformed, or revoked key. Body shape: {"app_exception": "Unauthorized", "context": null}.
  • 403 Forbidden — valid key, but the current plan does not include the requested API access, ticker, report, live data stream, or date range.
  • 429 Too Many Requests — per-key rate limit exceeded. Default limits include 30 requests / 60 s (sustained), 5 requests / 5 s (burst), and 500 requests / hour. Body: {"detail": "API key rate limit exceeded"}. Use exponential backoff before retrying.

​
rotation

  1. generate a new key in Settings → API Keys.
  2. deploy the new key to your integration.
  3. revoke the old key — it stops authenticating immediately.
manual only. no scheduled expiry. multiple active keys per account allowed — useful for staged rollouts.

​
best practices

  • store in environment variables / secret manager. never commit to source.
  • don’t log full keys server- or client-side. mask all but last 4 chars.
  • rotate when staff with access to the value leaves.