Authentication

All API endpoints require an API key. There is no anonymous tier — even the free plan requires a signed-up account and a generated key.

Getting a key

Create a key at portal.thesma.dev/dashboard → API keys → Create key. The plaintext key is shown once at creation; the server stores only a SHA-256 hash.

Passing the key

The API accepts two header formats for the same key. Both are equivalent — the same middleware validates either.

X-API-Key (primary)

The format shown in all marketing copy, blog posts, and recipes. Prefer this.

curl -H "X-API-Key: gd_live_a1b2c3d4..." \
  "https://api.thesma.dev/v1/us/sec/companies/AAPL"

Authorization: Bearer

The conventional REST form. Accepted by the same middleware; same key.

curl -H "Authorization: Bearer gd_live_a1b2c3d4..." \
  "https://api.thesma.dev/v1/us/sec/companies/AAPL"

Pick one per codebase and be consistent. Mixing them in the same application works but has no benefit.

Environment variable

The Python SDK, CLI, and most integration examples read the key from the THESMA_API_KEY environment variable if it is set. Exporting the key in your shell is the least-friction option:

export THESMA_API_KEY="gd_live_a1b2c3d4..."

from thesma import ThesmaClient

client = ThesmaClient()  # reads THESMA_API_KEY from the environment

Key format

Part	Value
Prefix	gd_live_
Suffix	128-bit random hex (32 characters)
Total length	40 characters
Storage	Plaintext shown once at creation; server stores SHA-256 hash only

The gd_live_ prefix identifies Thesma production keys. Don’t paste keys starting with any other prefix (e.g., th_live_ from older SDK versions) — those will fail authentication against the current API.

Error shapes

401 Unauthorized — missing or invalid key

{
  "error": {
    "code": "unauthorized",
    "message": "Missing API key. Include it as 'Authorization: Bearer <key>' or 'X-API-Key: <key>'.",
    "status": 401
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or revoked API key.",
    "status": 401
  }
}

403 Forbidden — key is disabled or the account is suspended

{
  "error": {
    "code": "unauthorized",
    "message": "Account is suspended.",
    "status": 403
  }
}

For the full error catalogue (status codes, error.code values, common causes), see Errors.