Authentication

Every request needs an API key.

Create a key in the dashboard. Copy it right away: you only see the full value once. All keys start with cmp_.

Send the key in the X-API-Key header on every request.

Where to put the key

Store your key in the COMPRESR_API_KEY environment variable. The SDKs read it for you. With cURL, pass it as a header on each call.

The SDKs set the X-API-Key header for you on every request. You only attach it by hand when calling the REST API directly.

Credential resolution

Both SDKs walk a fallback chain and use the first hit.

Python — explicit api_key= → COMPRESR_API_KEY env → INI file at ~/.compresr/credentials. The INI profile is selected via COMPRESR_PROFILE (defaults to default).

TypeScript — explicit apiKey → process.env.COMPRESR_API_KEY. File-based pickup is opt-in: import { createClient } from '@compresr/sdk/auth'. That helper reads JSON at ~/.compresr/credentials.json.

Format asymmetry is intentional: Python uses INI at ~/.compresr/credentials (no extension), TS uses JSON at ~/.compresr/credentials.json. Different files, different formats — do not share or symlink them.

CLI: compresr-sdk login / logout

Both SDKs ship a compresr-sdk binary.

• compresr-sdk login opens a browser flow and writes credentials to the local file (INI for Python, JSON for TS).
• compresr-sdk logout clears the local file and best-effort revokes the key server-side via POST /api/authorize/logout.

Deleting ~/.compresr/credentials (or credentials.json) by hand only removes the local copy — the key stays ACTIVE server-side. Use compresr-sdk logout to revoke it.

Base URL and insecure transport

Python reads COMPRESR_BASE_URL as a fallback. TypeScript does not — TS users must pass baseUrl explicitly to the client constructor.

Both SDKs refuse to start against a non-HTTPS base_url and raise CompresrError(code="insecure_base_url"). Set COMPRESR_ALLOW_INSECURE=1 to override. Loopback hosts (localhost, 127.0.0.1) are exempt from the check.

Key format

Every Compresr key starts with cmp_. Treat the full string as a secret - it is not recoverable, so if you lose it, revoke the old key and create a new one.

The SDKs validate the cmp_ prefix client-side before any HTTP call: Python raises AuthenticationError ("Invalid API key format. Keys must start with 'cmp_'"), TS throws the same. A present-but-invalid key that reaches the server returns 401 Unauthorized.

Requests with a valid key but an exhausted budget return 402 Payment Required. Requests with a wrong-scope key (e.g. a demo key on a paid endpoint) return 403 with code: 'scope_error' (ScopeError in the SDKs).

Omitting the X-API-Key header entirely returns 422 with FastAPI's default envelope ({"detail":[...]}), not the standard error envelope. Only a present-but-invalid key returns 401 with the documented envelope shape.

Best practices

• Use environment variables. Read keys from COMPRESR_API_KEY in every environment - local, CI, staging, production.
• Never commit keys. Add .env to .gitignore. Use a secret manager (1Password, Vault, AWS Secrets Manager, etc.) for production.
• Server-side only. Never embed a key in a browser bundle, mobile app, or any client-side code. The browser will leak it.
• Rotate regularly. Rotate every 90 days, and immediately if a key may have been exposed.
• Set a budget. Cap each key's monthly spend in the dashboard so a leak or runaway loop cannot drain your account.

Rotating a key

Create a new key in the dashboard and deploy it to your environments. Once you have confirmed traffic is flowing on the new key, delete the old one. Keys are revoked immediately on deletion - there is no grace period.

Budgets and expiry

Each key can carry a monthly budget cap and an optional expiry date, both set at creation in the dashboard. When the budget is exhausted, further requests with that key return 402 Payment Required until the next billing cycle or until you raise the cap. Expired keys return 401 Unauthorized after their expiry timestamp.