Skip to Content
AuthenticationScopes

Scopes

Every API key carries a scope that limits what it can do. You pick the scope when minting the key; you can’t change it after — to change scope, mint a new key and revoke the old.

The four scopes

USER — full portal-equivalent REST access

What a human in the portal can do, via API. Covers the entire REST surface under /api/scraper-api/.... Cannot use the MCP gateway — USER-scope keys against mcp.scrapewise.ai get 403 scope_rejected.

Pick this for: your own server-side code, CLI scripts, CI pipelines, integrations where you don’t need an AI agent.

LLM_READ — read-only MCP gateway access

For AI agents that you trust to look but not change anything. Can call:

  • list_* tools (scrapers, groups, schemas, jobs, data)
  • get_* tools (single-entity reads)
  • whoami
  • Preview tools (preview_scraper_from_url) — these don’t save state

Cannot call:

  • create_* / update_* / delete_* tools (any state mutation)
  • run_scraper (jobs cost compute)
  • Schema or scraper management

Pick this for: Claude Desktop / Claude Code where you want the agent to help you EXPLORE Scrapewise without risk of accidentally deleting a scraper.

LLM_FULL — read + write MCP gateway access

Same as LLM_READ plus all write/destructive operations. Can do anything via MCP that a USER-scope key can do via REST.

Pick this for: AI agents authorized to take actions on your behalf. Claude can create scrapers, run them, delete data. Use deliberately — there’s no separate per-tool consent.

MCP_GATEWAY — internal-only

Used by the MCP gateway service itself to call scraper-api. Not customer-mintable — you can’t create one from the portal. Mentioned here for completeness; you won’t see it in your key list.

Scope × operation matrix

OperationUSERLLM_READLLM_FULLMCP_GATEWAY
REST /api/scraper-api/*✅———
MCP /mcp (read tools)—✅✅✅
MCP /mcp (write tools)—❌✅✅
MCP /mcp (destructive)—❌✅✅
Portal-managed JWT auth✅———
/whoami✅✅✅✅
generate_api_key (mint child)✅❌❌—
delete_api_key (revoke)✅❌❌—

The MCP gateway routes calls through its own scope-filtering layer; USER keys are explicitly rejected by the gateway regardless of which tool they call.

Which scope should I use?

Decision flow:

Will an AI agent be calling Scrapewise?
├── No  → USER
└── Yes
    ├── Should the agent be able to delete / mutate data?
    │   ├── No  → LLM_READ
    │   └── Yes → LLM_FULL

When in doubt, start narrower. You can always mint a higher-scope key later when you need it.

Scope mismatch — what the error looks like

If you call a tool your scope can’t access, you get:

{
  "error": {
    "code": "403",
    "message": "scope_rejected",
    "data": {
      "scope": "LLM_READ",
      "requiredScope": "LLM_FULL",
      "tool": "scrapewise_delete_scraper"
    }
  }
}

(For REST, the same logic returns HTTP 403 with the same envelope structure.)

What’s next

API keysError envelope