# Authentication

Every API request must be authenticated using a product-scoped API key as a **Bearer token** in the `Authorization` header.

```bash
Authorization: Bearer YOUR_API_KEY
```

## Example Request

```bash
curl \
  "https://api.cutemarkets.com/v1/options/chain/NFLX/?limit=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Sample Response

```json
{
  "status": "OK",
  "request_id": "cm_adce10cb073745c7b859fc8131b203b0",
  "results": [
    {
      "break_even_price": 100.025,
      "details": {
        "contract_type": "call",
        "expiration_date": "2026-04-02",
        "strike_price": 100,
        "ticker": "O:NFLX260402C00100000"
      }
    }
  ]
}
```

## Getting your API key

[Sign up for free](/signup), and your first Options API key is automatically generated. No credit card required.

You can create additional Options API keys and Stocks API keys from your dashboard. Options keys work with `/v1/options/` and `/v1/tickers/expirations/`; Stocks keys work with `/v1/stocks/`.

## Product-scoped key model

CuteMarkets keys are intentionally product-scoped. An Options API key authorizes options routes and expiration lookup routes; a Stocks API key authorizes stock REST routes. Keeping the scopes separate makes billing, rate limits, and incident debugging easier because a failing request can be tied to one product surface rather than an account-wide credential.

| Key type | Accepted path families | Common first request | Typical mistake |
| --- | --- | --- | --- |
| Options API key | `/v1/options/`, `/v1/tickers/expirations/` | `/v1/options/chain/SPY/` | Using it for `/v1/stocks/quotes/` and expecting stock quote access. |
| Stocks API key | `/v1/stocks/` | `/v1/stocks/snapshot/AAPL/` | Using it for option chains or OCC contract lookups. |
| WebSocket access | WebSocket gateway docs | `/docs/websockets` | Reusing a REST-only test without checking the streaming plan. |

<svg viewBox="0 0 760 150" role="img" aria-label="Authentication flow from client to product scoped endpoint" style="max-width:100%;height:auto;border:1px solid #eadfd6;border-radius:12px;background:#fbf4ef">
  <rect x="28" y="42" width="150" height="58" rx="10" fill="#fffaf6" stroke="#db823f" stroke-width="2"/>
  <text x="103" y="68" text-anchor="middle" font-size="14" font-family="Inter, sans-serif" fill="#141111" font-weight="700">Client</text>
  <text x="103" y="87" text-anchor="middle" font-size="11" font-family="monospace" fill="#6d625b">Bearer key</text>
  <path d="M190 71H310" stroke="#db823f" stroke-width="3" marker-end="url(#arrowAuth)"/>
  <rect x="320" y="30" width="170" height="82" rx="10" fill="#fffaf6" stroke="#2f2e2e" stroke-width="1.5"/>
  <text x="405" y="59" text-anchor="middle" font-size="14" font-family="Inter, sans-serif" fill="#141111" font-weight="700">Auth check</text>
  <text x="405" y="80" text-anchor="middle" font-size="11" font-family="monospace" fill="#6d625b">scope + plan + limits</text>
  <path d="M500 71H620" stroke="#db823f" stroke-width="3" marker-end="url(#arrowAuth)"/>
  <rect x="630" y="42" width="104" height="58" rx="10" fill="#fffaf6" stroke="#1a7a50" stroke-width="2"/>
  <text x="682" y="68" text-anchor="middle" font-size="14" font-family="Inter, sans-serif" fill="#141111" font-weight="700">Endpoint</text>
  <text x="682" y="87" text-anchor="middle" font-size="11" font-family="monospace" fill="#6d625b">OK / ERROR</text>
  <defs><marker id="arrowAuth" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto"><path d="M0,0 L0,6 L7,3 z" fill="#db823f"/></marker></defs>
</svg>

## Debugging authentication failures

Start with the response envelope. A missing or malformed header normally returns `unauthorized`. A valid key with the wrong product or plan can return `forbidden` or a plan-specific upgrade error. A valid key that is making too many requests returns `rate_limit_exceeded`; keep the `request_id` from that response when contacting support.

In production, avoid logging full API keys. Log the route family, product, status code, error code, request id, and the non-secret key label from your own system. That gives enough context to reproduce the issue without putting credentials in application logs.

## Environment setup

Use separate environment variables for separate product keys. This reduces accidental cross-product calls and makes deployment reviews easier. A backend that supports both stock and options workflows should choose the key at the integration boundary, not deep inside endpoint-specific code.

```text
CUTEMARKETS_OPTIONS_API_KEY=...
CUTEMARKETS_STOCKS_API_KEY=...
```

For browser applications, do not expose API keys directly to the client. Route requests through your backend, apply your own user authorization, and keep CuteMarkets credentials in server-side configuration. If an integration must run from a local notebook or command-line tool, load the key from the environment rather than committing it to source code.

## Key rotation and operations

Treat API keys like production credentials. Give each key a clear label in your own secret manager, record which service uses it, and rotate keys when a developer leaves a project or a deployment environment is replaced. During rotation, deploy the new key first, verify a low-risk endpoint, then remove the old key from the running environment.

When investigating auth failures, check the path family before checking code. A request to `/v1/stocks/quotes/` with an Options API key is a configuration problem, not a networking problem. A request with the right product key but insufficient quote entitlement is a plan problem. Logging the product label and route family makes that distinction obvious.