Authentication & API keys

Every request to http://localhost:4000 must include an API key in the x-api-key header:

curl "http://localhost:4000/v1/usage" -H "x-api-key: YOUR_API_KEY"

The x_api_key query parameter is still accepted for backwards compatibility but is deprecated: query strings end up in logs and browser history. Always use the header.

Creating keys

Open API Keys in the dashboard and click Create key. Each key has:

The full key is displayed only once at creation. We store a hash, so we can't show it again — create a new key if you lose it.

Per-key quotas

Quotas cap how many requests a single key can make, independently of your plan. They're ideal for giving a key to a contractor, a staging environment or a customer-facing integration.

When a quota is reached, requests return 401 with a message naming the window:

{ "error": "Rate limit exceeded for the API key: quota daily" }

Quotas are rolling windows, so capacity frees up gradually as older requests age out. Quota errors are not retried by the official SDKs.

Lifecycle: deactivate, archive, restore, delete

• Deactivate — temporarily reject requests; reactivate any time.
• Archive — hide a retired key from the default list and reject its requests. Its logs and analytics remain.
• Restore — bring an archived key back.
• Delete — permanently remove a key. Only possible for keys that have never been used; keys with history must be archived so logs and billing stay consistent.

Rotating keys

Rotate keys regularly and immediately if one may have leaked:

1. Create a new key with the same category and quotas.
2. Deploy the new key to your environment (secret manager, environment variable).
3. Watch API Logs until the old key receives no more traffic.
4. Deactivate the old key, then archive it.

Because each key has its own alias, logs show exactly which services still use the old one.

Keeping keys safe

• Never embed keys in client-side code, mobile apps or public repositories. Call ScreenshotDude from your backend.
• Use one key per environment and per service.
• Use quotas and expiry dates for keys you share.
• If a key leaks, deactivate it first, then rotate.

IP blocking

After repeated failed authentication attempts from the same IP address, that IP is temporarily blocked and receives:

{ "error": "IP temporarily blocked" }

with status 403. The block lifts automatically after a cool-down. Check that you are sending the correct key before retrying.

Error reference

Note that rate limits return 401, not 429. See Status codes.

Plan rate limits