Authentication.

01Authentication scheme

Every request to api.hypedata.io must carry an Authorization header with a bearer token. We also accept the key as a query parameter (?api_key=…) for environments where setting headers is impractical, but never use the query form for production traffic — URLs are logged by intermediaries and frequently leak into analytics, browser history, and CDN logs.

Authorization: Bearer hd_live_8K2nB7q4XwY1pVzR9tL6mDfC0sJaE3gH

# Don't use in production — URL params leak.
GET /v1/scrape?url=…&api_key=hd_live_…

TLS 1.2+ is required. Plain-HTTP requests redirect to HTTPS, which is fine for occasional one-off use but will double your latency if relied on at scale.

02Key format

Keys follow the format:

hd_{env}_{32 url-safe characters}

We do not provide a way to set a custom key — they're issued by the platform so we can guarantee uniqueness, entropy, and revocability.

03Live vs. test keys

Both key types hit the same hostname (api.hypedata.io) and the same endpoints. The server inspects the prefix and routes accordingly.

04Scopes & restrictions

From app.hypedata.io/keys, each key can be locked down on three axes:

Endpoint scope

Choose which endpoints the key may call. A scraping-only key cannot hit billing endpoints; a read-only key cannot create batches. Available scopes:

• scrape — POST/GET /v1/scrape
• serp — GET /v1/serp
• parse — POST /v1/parse
• stream — open /v1/stream
• jobs — manage batches
• billing — read-only access to usage and invoices
• admin — manage workspace, members, keys (high-trust)

IP allow-list

Restrict the key to a list of source CIDRs. The request is rejected with 403 unauthorized_ip if it arrives from anywhere else. Particularly useful for production keys called from a fixed egress NAT.

Credit ceiling

Cap the lifetime credit spend of a single key. Once the ceiling is hit, every request returns 402 key_ceiling_exceeded — without affecting the rest of the workspace. Great for handing out limited keys to partners or contractors.

05Rotation

Keys never expire on their own, but we strongly recommend rotating annually — or immediately if anyone with access to the key leaves the team.

1. Create a second key in the same project.
2. Deploy your services with the new key.
3. Watch the old key's traffic in the dashboard drop to zero.
4. Revoke the old key.

Keys can also be set with a scheduled expiry in the dashboard. The system emails the workspace owners 30, 7, and 1 day(s) before expiry, then disables the key automatically.

06Revocation

Revoking a key takes effect globally within five seconds. The revoked key returns 401 revoked on its very next request, and any open Stream API connection is closed with a final auth_revoked event.

curl -X DELETE https://api.hypedata.io/v1/keys/key_8K2nB7 \
  -H "Authorization: Bearer $HYPEDATA_ADMIN_KEY"

await hd.keys.revoke("key_8K2nB7");

Revocation requires a key with the admin scope, or session auth from a workspace owner in the dashboard.

07Leak detection

Every 15 minutes, Hypedata scans GitHub, GitLab, npm, PyPI, RubyGems, and a handful of paste sites for tokens matching the hd_live_* pattern. Any match triggers:

• Immediate automatic revocation of the leaked key.
• Email + Slack notification to the workspace owners with the source URL and a diff link.
• A pre-created replacement key with the same scopes, ready to deploy.
• An audit-log entry visible in the dashboard.

You can opt out of auto-revocation in Settings → Security if it conflicts with your incident-response process — but we strongly recommend leaving it on.

08Auth errors

Auth errors carry a WWW-Authenticate: Bearer error="…" header with a machine-readable error code, in addition to the JSON body.