> ## Documentation Index
> Fetch the complete documentation index at: https://edgeful.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# authentication: edgeful API keys

> authenticate edgeful API requests with API keys over HTTP Bearer auth. header format, key rotation, rate-limit errors, and secure storage.

## 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:

<CodeGroup>
  ```bash curl theme={null}
  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"
  ```

  ```python Python theme={null}
  import os, requests
  r = requests.get(
      "https://api.edgeful.com/report_calculation/outside-days-standard/futures/SPY",
      params={"start_date": "2024-01-01", "end_date": "2024-12-31"},
      headers={"Authorization": f"Bearer {os.environ['EDGEFUL_API_KEY']}"},
  )
  print(r.json())
  ```

  ```javascript JavaScript theme={null}
  const apiKey = process.env.EDGEFUL_API_KEY;
  const res = await fetch(
    "https://api.edgeful.com/report_calculation/outside-days-standard/futures/SPY?start_date=2024-01-01&end_date=2024-12-31",
    { headers: { Authorization: `Bearer ${apiKey}` } }
  );
  console.log(await res.json());
  ```
</CodeGroup>

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

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