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 manual API calls step 2:

​
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, all available history with no rolling cutoff, live data included, detailed rows included when available.
  • All Access: all report endpoints and supported tickers, all available history with no rolling cutoff, live data included, detailed rows included when available.
the discovery scan (/discovery/scan) applies the same per-plan ticker allow-list and history window — its lookback (1mo, 3mo, 6mo, 1y) is capped to your plan’s months of history. it does not apply the report limit: every plan sees all report families ranked in the discovery results. 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. limits are the same on every plan: 120 requests / 60 s (sustained), 30 requests / 10 s (burst), and 1,500 requests / hour. body: {"detail": "API key rate limit exceeded"}. use exponential backoff before retrying.
the settings and custom-report routes under /v1 add a few of their own: 400 with a detail message naming the valid values, 403 with a code (writes_disabled when the key’s writes are off), 404 for a custom report that is not yours, 409 for a custom-report run that cannot start, 422 for a malformed body, and a second kind of 429 with Retry-After when the account’s settings, custom-report or run budget, shared with Claude, is exhausted. see manage your settings with the API for the full table and the retry rules.

​
versioning

routes under /v1 only grow: new routes, fields and codes may appear without notice, and a documented route, field, status or code is not removed or renamed under /v1. the report, discovery and live routes keep their existing paths.

​
rotation

  1. click regenerate on your key in the API dashboard.
  2. copy the new key — regeneration revokes the previous key through the key provider.
  3. deploy the new key to your integration.
confirm the previous key is rejected before treating rotation as complete; revocation can take time to propagate. manual only. no scheduled expiry. one active key per account — to replace it, regenerate it or revoke it and create a new one.

​
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.