Early access is open. Free sample datasets are live now. Download a sample

API Keys and Authentication

Details

Docs navigation

Every request to the marketdata.co API carries one API key. This page shows the two ways to send it, how to store it so it does not end up on GitHub, and what the 401 and 403 errors mean. Read it once before you put a market data API key into a script, a spreadsheet or a server.

Early access. Keys are issued when the API opens. Join early access to be on the first list.

How it works

How to authenticate

1. Find your key

Open Account > API keys in the dashboard. Each account starts with one key. You can add more, name them (for example backtest-laptop or prod-server) and revoke any of them on its own.

2. Send it in the Authorization header (preferred)

Example (curl):

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.marketdata.co/v1/reference/market-status"

Header auth keeps the key out of URLs, so it does not land in proxy logs, browser history or shared links.

3. Or send it as a query parameter

Some tools cannot set headers. Google Sheets IMPORTDATA and Excel's basic web import are the usual examples. For those, add apikey:

https://api.marketdata.co/v1/stocks/bars?symbol=AAPL&interval=1d&format=csv&apikey=YOUR_API_KEY

Anyone who can see that URL can use your key. Use a separate, named key for spreadsheets so you can revoke it without breaking your other code.

4. Keep the key out of your code

Store it in an environment variable and read it at run time:

export MARKETDATA_API_KEY="paste-your-key-here"

Example (Python):

import os
import requests

key = os.environ["MARKETDATA_API_KEY"]
r = requests.get(
    "https://api.marketdata.co/v1/reference/market-status",
    headers={"Authorization": f"Bearer {key}"},
)
print(r.status_code, r.json())

Add .env to .gitignore if you keep keys in a dotenv file. Never ship a key inside a browser app or a mobile app; call the API from your own server instead.

5. Rotate a key

Create a new key, deploy it, then revoke the old one. A revoked key fails on its next request. There is no grace period, so swap first and revoke second.

6. Authenticate a WebSocket

Streaming connections send the key in the first message after connecting, not in the URL. See the WebSocket streaming guide.

Details

Errors you may see

HTTP status error.code What it means Fix
401 missing_api_key No header and no apikey parameter Add the Authorization: Bearer header
401 invalid_api_key Key is wrong, revoked or has a typo Copy it again from the dashboard
403 plan_required The key is valid but your plan does not include this data Check the plan named in error.message or upgrade on pricing
403 commercial_use_required The endpoint needs a commercial licence Business plan ($249/mo) or Enterprise

Example error body:

{
  "status": "error",
  "error": {
    "code": "plan_required",
    "message": "Real-time option chains need the Pro plan or higher.",
    "request_id": "req_7f3c91a2"
  }
}

Watch out

Notes and gotchas

  • The Bearer prefix and a single space are required. Authorization: YOUR_API_KEY without the prefix returns invalid_api_key.
  • If you send both a header and an apikey parameter, the header wins.
  • Keys are per account, and plan limits apply to the account. Three keys do not give you three times the rate limit.
  • Quote the request_id when you contact support. It lets us find the exact call.
  • A 403 is not a broken key. Retrying will not fix it.
  • Real-time US stock and options data is licensed per user. One key belongs to one person unless you are on a commercial plan.

Keep reading

Next steps

Details

Was this page useful?

[Yes] [No]

Something unclear about keys or access? Tell us on the custom data form.