API Keys and Authentication
Details
Docs navigation
- Getting started: Quickstart, Authentication (you are here), Rate limits, Errors and retries
- Guides: Symbol formats, Timestamps and time zones, Pagination, Split and dividend adjustments, WebSocket streaming, Dataset downloads, Excel and Google Sheets, Changelog
- API reference: Stock bars, Stock trades and quotes, Snapshots and movers, Tickers, exchanges, calendar, Splits and dividends, Fundamentals and SEC filings, Options chain and Greeks, Options EOD, bars, OI, Forex, Crypto, Crypto derivatives, Futures bars and continuous, Settlements and COT, Indices, Economic data, Technical indicators
- SDKs: Python, JavaScript
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
Bearerprefix and a single space are required.Authorization: YOUR_API_KEYwithout the prefix returnsinvalid_api_key. - If you send both a header and an
apikeyparameter, 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_idwhen 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.