API keys

The full lifecycle: mint, list, use, rotate, revoke. Three paths to do each — portal UI (the easy way), REST API (programmatic), and MCP gateway (if Claude is helping you).

Format reminder

sw_live_abc1234.<long random secret>

sw_live_ env tag, 7-char prefix (public), random secret (private). See Authentication overview for the breakdown.

Mint

Via the portal (easiest)

1. Sign in to portal.scrapewise.ai 
2. Settings → API Keys → Create new key
3. Pick a name (descriptive label like prod-server, claude-desktop)
4. Pick a scope — see Scopes for the matrix
5. Click Create
6. Copy the key now — it’s only shown once

Via the REST API

curl -X PUT \
  -H "Authorization: Bearer $EXISTING_KEY" \
  "https://portal.scrapewise.ai/api/scraper-api/api/key/generate?name=my-new-key&scope=USER"

Response includes the full sw_live_<prefix>.<secret> value. Same caveat — copy it now; you cannot retrieve the secret later.

{
  "id": "...",
  "prefix": "abc1234",
  "name": "my-new-key",
  "scope": "USER",
  "key": "sw_live_abc1234.<secret>",
  "createdAt": "2026-05-19T12:30:00Z"
}

The key field is the only place the full secret appears. After this response, only the hash is stored.

List

Via the portal

Settings → API Keys shows a table with name, prefix, scope, created-at, and a trash icon per row. The secret is never displayed.

Via the REST API

curl -H "Authorization: Bearer $KEY" \
  "https://portal.scrapewise.ai/api/scraper-api/api/key/list"

Response:

{
  "keys": [
    {
      "id": "...",
      "prefix": "abc1234",
      "name": "my-laptop",
      "scope": "USER",
      "createdAt": "2026-05-10T...",
      "lastUsedAt": "2026-05-19T..."
    },
    ...
  ]
}

Revoke

Revocation is immediate — the next request with that key returns 401. There’s no grace period and no soft-delete.

Via the portal

Settings → API Keys → trash icon next to the key → confirm.

Via the REST API

# Use the id (not the prefix) from /api/key/list
curl -X DELETE -H "Authorization: Bearer $KEY" \
  "https://portal.scrapewise.ai/api/scraper-api/api/key/{id}"

Note: a key can revoke other keys (any-scope-revokes-any) within the same customer. A key can also revoke itself, though normally you’d use a different key to do this to avoid surprises.

Rotate

Scrapewise doesn’t have a “rotate” endpoint — rotation is mint-then-revoke:

1. Mint a new key with the same name + scope
2. Deploy / update wherever the old key was used
3. Revoke the old key

You can run new + old in parallel for as long as you need to roll out the change — there’s no max-keys limit per customer.

Best practices

• One key per surface: mint a separate key for each integration (your CI, your Claude Desktop, your laptop, your prod server). Easier to revoke one without affecting the others.
• Don’t commit keys to git: pass via env var (export SCRAPEWISE_KEY=sw_live_...) or a secrets manager. Both Bitbucket and GitHub will block known Scrapewise key formats from being pushed in plaintext if you enable secret-scanning.
• Scope minimum needed: USER for your own scripts, LLM_READ for Claude (read-only), LLM_FULL only when Claude needs to mutate.
• Audit periodically: GET /api/key/list shows lastUsedAt per key. Revoke keys you don’t recognize.

Verifying a key works

The fastest sanity check:

curl -H "Authorization: Bearer $KEY" \
  https://portal.scrapewise.ai/api/scraper-api/api/key/whoami

200 + JSON with your customerRef + scope + prefix = key is good.

401 = key is invalid or revoked.

Common errors

What’s next

• Scope semantics → Scopes
• Error envelopes → Errors
• Use a key from Claude → MCP quickstart