Authentication

Every request to REST and WebSocket carries an API key in a Bearer header. Keys belong to an account, carry scopes that match your plan and can be rotated without downtime.

Key types

A key is the prefix followed by 32 base62 characters, for example fdc_live_Qm4T8wZr2KxN7bVc1HsJ5pLe9YgA3dFu. The full key is shown once, when it is created; we store only a salted hash of it. Afterwards the console shows only the prefix and the last four characters (for example fdc_live_…3dFu), so store it in a secret manager at creation time.

Test keys do not count toward rate limits on your plan and are capped at 5 requests per second. They work with every interface, so CI can run the same code paths as production.

Sending the key

Send the key in the Authorization header on every request. Keys in query strings are rejected, because URLs end up in proxy and server logs.

curl https://api.financedatacloud.com/v1/instruments?venue=hyperliquid \
  -H "Authorization: Bearer fdc_live_Qm4T8wZr2KxN7bVc1HsJ5pLe9YgA3dFu"

import os
from fdc import Client

fdc = Client(api_key=os.environ["FDC_API_KEY"])
# or Client() with FDC_API_KEY set; the SDK reads it automatically

# 1. Preferred: header on the HTTP upgrade request
GET /v1 HTTP/1.1
Host: stream.financedatacloud.com
Upgrade: websocket
Authorization: Bearer fdc_live_Qm4T8wZr2KxN7bVc1HsJ5pLe9YgA3dFu

# 2. Clients that cannot set headers: send this as the first frame,
#    within 5 seconds of connecting
{"op":"auth","api_key":"fdc_live_Qm4T8wZr2KxN7bVc1HsJ5pLe9YgA3dFu"}

Do not ship a key in browser or mobile code. Anyone who can read the bundle can read the key. Proxy requests through your own backend instead.

Bulk S3 does not use API keys. Access to s3://fdc-archive is granted to the AWS account IDs you register, and requests are signed with your own AWS credentials. See Bulk S3.

Scopes

Each key carries one or more scopes. A new key gets every scope your plan includes; you can create narrower keys, for example a historical-only key for a research cluster that should never open a live connection.

Scopes control interfaces. Your plan separately controls datasets: a Researcher key with the historical scope still cannot read book_l3, which is a Desk dataset. Both checks return 403, with different error codes (below). Plan contents are on Pricing.

Rotating keys

An account can hold up to 10 active keys at once, so rotation never needs downtime.

We recommend rotating at least every 90 days and whenever someone with access leaves. If a key leaks, revoke it first and investigate second; then tell us at daniel@financedatacloud.com so we can review access logs with you. We scan public GitHub repositories for strings with our key prefixes and revoke matches automatically, with an email to the account owner.

IP allowlists

Enterprise accounts can restrict each key to a set of source addresses. Requests from any other address are refused with 403 ip_not_allowed, even with a valid key.

• Up to 50 entries per key, IPv4 or IPv6, as single addresses or CIDR ranges (203.0.113.0/24, 2001:db8:4f::/48).
• Applies to REST and WebSocket. S3 is governed by your own AWS IAM policies instead.
• Changes propagate within 60 seconds. Existing WebSocket connections from an address that is removed are closed.
• For Tokyo cross-connect customers, the allowlist is pre-filled with the cross-connect range.

Allowlists are configured by account admins in the console, or by request to daniel@financedatacloud.com.

Errors

Authentication and authorization failures use the same error body as the rest of the API: an error object with the HTTP status, a stable machine-readable code, a human-readable message and the request_id, which is also returned in the X-Request-Id header.

{
  "error": {
    "status": 403,
    "code": "plan_required",
    "message": "book_l3 is not included in the Researcher plan.",
    "request_id": "req_01JA7Q3V8K2M4XR9T6WZB5NDHC"
  }
}

401 Unauthorized

The request could not be tied to a valid key. Do not retry with the same key.

403 Forbidden

The key is valid but not allowed to do this. Retrying will not help until the key, plan or request changes.

On WebSocket, the same codes arrive as an error frame followed by a close with code 4401 (authentication) or 4403 (authorization). Rate limiting (429) is covered on Rate limits, and the full error list on REST API.