Skip to main content

Setting up: API keys, environment hygiene, and key lifecycle

Getting an API key​

Your API key is the credential the server uses to identify you and decide which datasets you are allowed to see. It is issued out of band — typically by your account contact at algoseek — and looks like a short opaque string of letters, digits, hyphens, and underscores (roughly 35 characters). Treat it as opaque: do not parse it or assume any internal structure.

A single account can hold multiple keys (see the GET /api/v1/api-keys family). Quotas are enforced at the account level (see the quotas chapter); issuing one key per service buys you the ability to revoke a single service without invalidating the others, not more headroom.

Where to put the key (and where not to)​

warning

Never check your API key into source control, never paste it into a public chat or issue tracker, and never embed it in client-side code shipped to a browser. The key gives any holder full read access to every dataset your account is entitled to, and its loss would consume your monthly quota until rotated.

The single best place to keep your key during development is an environment variable. Every example in this guide reads the key from the variable named ALGOSEEK_API_KEY.

macOS and Linux.​

Set the key for the current shell session.
export ALGOSEEK_API_KEY="paste-your-key-here"

# Confirm it is set (the value should be echoed):
echo "${ALGOSEEK_API_KEY:0:6}..."   # prints first 6 chars then dots

To make the export persistent across new terminal sessions, append the export line to your shell rc file (~/.bashrc, ~/.zshrc, or ~/.profile).

Windows (PowerShell).​

PowerShell equivalent. [Environment]::SetEnvironmentVariable with the User target persists the key across sessions.
$Env:ALGOSEEK_API_KEY = "paste-your-key-here"
[Environment]::SetEnvironmentVariable("ALGOSEEK_API_KEY", $Env:ALGOSEEK_API_KEY, "User")

Reading it from Python.​

Read the key in your script and refuse to run if it is missing. Failing fast is much friendlier than sending an unauthenticated request.
import os, sys

API_KEY = os.environ.get("ALGOSEEK_API_KEY", "").strip()
if not API_KEY:
    sys.exit(
        "ALGOSEEK_API_KEY env var not set. "
        "Add 'export ALGOSEEK_API_KEY=...' to your shell rc."
    )

Project-local options.​

For multi-developer projects, an env-loader file like .env (parsed by python-dotenv, node --env-file, or godotenv) is convenient. Treat .env like a secret: add it to .gitignore, never commit it, and check it into your secrets manager (1Password, Vault, AWS Secrets Manager) instead. For production, prefer the secrets-manager API directly — read the key into memory at process startup, never write it to disk, and never log it (mask all but the first six characters when emitting diagnostics).

Key rotation hygiene.​

When a key is rotated, the old key is revoked immediately on the server side. Plan for in-flight requests on the old key returning 401 during the cutover; either drain your worker pool first, or keep a brief grace period during which both keys are valid (issue the new key, switch your config, then deactivate the old one via POST /api/v1/api-keys/{key_id}/deactivate). Note: the api-keys/* family is admin-only. If your key is not an admin key the deactivate call will return 403; in that case arrange rotation through your account contact rather than calling the endpoint directly.

Quota implications.​

Multi-key shops adopt the pattern for the per-key audit trail (attribute usage and revoke individual integrations); not for headroom (see the quotas chapter).

The two-step verification of a working setup​

Before writing any data-pulling code, run two short probes to make sure your key is wired up correctly. Each probe takes about a second and tells you something the next chapters will assume.

Probe 1: the server is reachable. No auth required.
curl -s "https://dev-datasets-api.algoseek.com/api/v1/status"
Captured response body — sys_status
{
  "status": "OK",
  "version": "0.2.0"
}
Probe 2: your key is valid and the server has identified you. This call requires the X-API-KEY header.
curl -s "https://dev-datasets-api.algoseek.com/api/v1/account/my" \
     -H "X-API-KEY: $ALGOSEEK_API_KEY"
Captured response body — iam_account_my
{
  "identity_id": 89,
  "name": "Algoseek Prod (REST API)",
  "max_active_api_keys": 15,
  "ip_subnets": []
}

If both probes return 200 and the second one shows your account in the name field (not somebody else's, not an error envelope), your setup is correct and you are ready for the authentication chapter.

note

What's runnable on the dev key. The dev environment is provisioned with a small subset of datasets. Throughout this guide, worked examples that need a real dataset use one of: eq-trades (with adjusted=true, i.e. eq_trades_adj), eq-trades-1min, eq-market-holidays, eq-ipo, and eq-adj-factors-basic. Other datasets used as examples (options, futures, full TAQ) return 403 on the dev key and are shown for shape only.

note

Timeout policy used throughout this guide. Identity and catalog calls use a 30-second timeout; data-plane calls use 60 seconds; long-running streaming/CSV-gzip pulls use 5 minutes. Every code snippet you will see follows this policy unless explicitly called out.

The full identity envelope is rich enough to drive policy decisions in your client (e.g. refuse to run a pipeline if the entitlement window has shifted out from under you). The first-request chapter walks through every field of the envelope, and the catalog chapter walks through the endpoints that let you discover what each entitlement gives you.