API keys (security deep dive)

API keys grant programmatic access to Compresr. Treat them like passwords. Anyone with a valid key can call the API on your behalf and incur charges. This page covers lifecycle and incident-response concerns for ops and security teams. For the basics of obtaining a key and wiring it into the SDKs, see Authentication.

Key format

Every Compresr API key starts with the prefix cmp_ followed by a random secret. Keys are created in the dashboard and the full value is shown once at creation. There is no way to retrieve it later. Copy the key into your secret manager immediately. If you lose it, revoke the key and create a new one.

Storage

• Read keys from environment variables in every environment, typically COMPRESR_API_KEY. Never hardcode them in source files.
• Add .env (and any other secrets file) to .gitignore before you write your first key into it.
• In production, store keys in a real secret manager: AWS Secrets Manager, Google Secret Manager, HashiCorp Vault, Doppler, 1Password, or your platform's equivalent. Inject them at deploy time, not at build time.
• Never paste a key into chat, a ticket, a screenshot, a public Slack channel, or a shared doc. If you do, treat it as leaked.
• Do not embed keys in client-side code. The browser is not a trusted environment. Proxy compression calls through a server you control.

Rotation

Rotate keys on a schedule and immediately on any suspected compromise. A 90-day rotation cadence is a reasonable default for production keys; shorten it for keys with broad access. Use the dashboard to mint a new key, then deploy it before revoking the old one so traffic never drops.

1. 1

   Create a new key in the dashboard

   Mint the replacement key and copy it into your secret manager.
2. 2

   Deploy the new key alongside the old one

   Use a rolling deploy that picks up the updated COMPRESR_API_KEY so the old and new keys overlap.
3. 3

   Verify zero traffic on the old key

   Check the dashboard usage log and confirm the old key is no longer receiving requests.
4. 4

   Revoke the old key in the dashboard

   Revocation is immediate. Subsequent requests with that key return 401 Unauthorized.

Per-key budgets

Every key can be assigned a monthly USD budget at creation. Once the budget is exhausted, requests with that key return 402 Payment Required until the budget is increased or the key is rotated. The global account budget still applies on top.

Per-key budgets are a blast-radius control. If a key leaks and the budget is $50, the maximum exposure from that leak is $50 before the API starts rejecting requests. Use small budgets for keys handed to contractors, CI jobs, demo environments, or third-party integrations; reserve larger budgets for trusted production services.

Expiration

Keys can be created with an optional expires_at timestamp. Once a key passes its expiry it returns 401 Unauthorized and is functionally revoked. No separate action is required.

Expiring keys are useful for short-lived credentials: contractor access tied to an engagement window, time-boxed customer demos, or temporary CI credentials issued by a parent secret. For permanent production services, prefer a no-expiry key paired with a scheduled rotation.

What to do if a key is leaked

If you find a cmp_ key in a commit, a screenshot, a log, or anywhere it shouldn't be, treat it as compromised. Do not wait to confirm whether anyone actually saw it.

1. 1

   Revoke the key in the dashboard

   This is the only action that matters in the first minute. Revocation is immediate, and every subsequent request with that key returns 401 Unauthorized.
2. 2

   Rotate to a new key

   Create a replacement key in the dashboard, copy it into your secret manager, and deploy the new value to every environment that used the old one.
3. 3

   Audit the usage log for the leaked key

   Open the dashboard usage view and check for unexpected traffic: unfamiliar source IPs, traffic outside business hours, or spikes in token volume. Export the log if you need it for an incident review.
4. 4

   If unexpected charges occurred, contact support

   Email [email protected] with the masked key preview shown in the dashboard (e.g. `cmp_abc...xyz`) and the time window of suspicious activity. Never include the full key in the email — the masked preview is enough for us to identify it.

After the immediate response, scan the rest of your codebase for similar exposures. If one key ended up somewhere it shouldn't, others might have too. A repo-wide git log -S "cmp_" is a useful starting point.