Authentication

Warpweb uses Bearer tokens over HTTPS. Every request to api.warpweb.ai requires an Authorization header.

curl https://api.warpweb.ai/v1/sites \
  -H "Authorization: Bearer wpwb_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Requests without a valid key return 401 Unauthorized.

Key types

Warpweb issues two key types per account. Both authenticate against the same endpoints; the difference is intended exposure.

Prefix	Type	Intended use
`wpwb_pk_`	Publishable	Safe to embed in client-side code. Read-only operations and status polling.
`wpwb_sk_`	Secret	Server-side only. Required for all write operations (`POST` endpoints). Never ship to a browser.

For V1, both key types currently authorize all 8 endpoints — but treat wpwb_pk_ as if it were future-restricted to reads. A near-term update will tighten publishable keys to GET operations only.

Creating, rotating, revoking

All key management happens in the dashboard at app.warpweb.ai/api-keys.

Create — generates a new key. The plaintext value is shown once. Copy it immediately into your secret manager; we can’t retrieve it later.
Rotate — creates a new key with the same permissions and revokes the old one. Use this for periodic credential hygiene or after a suspected leak.
Revoke — invalidates a key immediately. Subsequent requests with that key get 401.

Multiple active keys per account are supported. Tag them by environment (prod, staging, ci) in the dashboard.

Rate limits

100 requests per minute per key, sliding window. GET operations and writes share the same bucket.

When you exceed the limit, Warpweb returns 429 Too Many Requests with a Retry-After header (seconds).

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json
 
{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Retry in 12 seconds."
}

Treat Retry-After as a hint — back off at least that long before retrying.

If 100 req/min is too tight for your use case, contact support; we’ll raise the cap for legitimate workloads.

Error responses

All authentication errors return JSON with a stable error code:

Status	`error` code	Cause
401	`missing_authorization`	No `Authorization` header.
401	`invalid_key`	Key not recognized, revoked, or expired.
401	`malformed_key`	Header present but doesn’t match the expected `Bearer wpwb_…` shape.
403	`insufficient_scope`	Publishable key used for a write operation (future enforcement).
429	`rate_limited`	Too many requests in the sliding window.

TLS

Warpweb requires TLS 1.2+. Plain HTTP requests are redirected to HTTPS but you should call HTTPS directly — credentials sent over HTTP will be logged as a security event and may auto-revoke the key.

Storing keys

Use your platform’s secret manager (Vercel env vars, AWS Secrets Manager, Doppler, 1Password, etc.).
Never commit keys to git. Warpweb scans GitHub for leaked keys with the wpwb_sk_ prefix and auto-revokes — you’ll get an email if this happens, but it’s an interruption you don’t want.
Rotate keys when team members with access leave.

Quickstart Overview