Authentication

The SupraBench API uses long-lived bearer tokens. Send them in the Authorization header on every request. There are no OAuth flows, no signed-request schemes, no expiring access tokens — just one header, one secret.

The Authorization header

Every request to /v1/ must include:

Authorization: Bearer sb_live_a1b2c3d4e5f6...<64 hex chars total>

Missing or malformed: 401 missing_token. Wrong prefix: 401 invalid_token_format. Unknown / revoked: 401 invalid_token. Subscription cancelled and grace period expired: 402 subscription_inactive.

Key format

Keys look like:

sb_live_3f1a8c2e4d6b9f7a0c5e8b2d4f6a8c1e3d5b7f9a0c2e4d6b8f0a2c4e6d8b0f2a
└──┬──┘└────────────────────────────┬────────────────────────────────┘
prefix     64 hex chars (32 random bytes, cryptographically generated)

The prefix indicates the environment. There is currently only one environment (sb_live_). A future sb_test_ tier may exist for sandbox testing without affecting your quota.

In our database we only ever store the SHA-256 hash of the key plus the first 8 hex chars (the "prefix display" you see in the dashboard). The plaintext is shown once at creation time and then forgotten by us.

Creating keys

1. Sign in at suprabench.com and open Profile → API & Billing.
2. Make sure you have an active subscription for the tier you want a key for.
3. Click Create new key, give it a descriptive name (free-form text, only you see it). Suggested convention: {environment}-{purpose}, e.g. prod-dashboard, laptop-research, ci-tests.
4. Copy the value immediately. Once you close the dialog, the plaintext is gone forever.

Why we don't show keys twice. Storing plaintext or reversibly encrypted secrets is the most common breach pattern in SaaS. We hash on creation and verify on each request. There's genuinely nothing to leak from our database — verified by anyone reading the open-source code.

How many keys can I have?

Revoked keys never count against the limit. Hitting the cap returns 422 max_keys_reached on the create endpoint.

Storing your key safely

• Never commit a key to git. Add it to .env and put .env in .gitignore.
• Never put a key in client-side JavaScript. Browser code can be read. Server-render or proxy through your backend.
• Use environment variables. All examples in our docs assume SUPRABENCH_KEY is set in the process env.
• Rotate yearly, or sooner after employee turnover or laptop loss. See Rotation.
• One key per surface. Don't share one key between prod, staging and three engineers' laptops — you can't tell who leaked.

Sample .env

# SupraBench API — production key. Rotate yearly.
SUPRABENCH_KEY=sb_live_3f1a8c2e...

Key rotation (zero downtime)

To rotate without dropping a single request, follow the standard "two keys for a moment" pattern:

1. In the dashboard, create a new key. Both old and new now work.
2. Deploy your services with the new key in SUPRABENCH_KEY.
3. Verify traffic is using the new key — the dashboard shows last-used-at per key.
4. Revoke the old key. 401 revoked begins for any straggler request still using it.

Revoking a key

Click Revoke next to the key in your dashboard. Revocation is effective immediately — the next request using that key gets 401 revoked. Revocation is a soft delete: the row stays in our DB so audit logs (which key did what) survive forever. Revoked keys are excluded from your active-keys count.

If you suspect a leak: revoke first, ask questions later. A new key takes 5 seconds to mint.

HTTPS only

Plain-HTTP requests to api.suprabench.com get 308 Permanent Redirect to HTTPS. Don't follow the redirect with your bearer token attached — most clients do this automatically and it's safe in our case (we don't strip headers cross-origin), but always send the original request as HTTPS to avoid leaking the key to an intermediary.

CORS

All /v1/ responses include Access-Control-Allow-Origin: *. Browser fetch() calls work, but remember: putting your key in browser code is unsafe regardless of CORS. Use a server-side proxy.

Audit log

Every authenticated request is logged with: timestamp, key ID, endpoint, status, response time, source IP, user agent. Logs are kept for 30 days and visible in the dashboard's per-key drill-down. Useful for spotting compromised keys (sudden traffic from unknown IPs).