Authentication overview
Every Scrapewise API call needs an Authorization: Bearer <token> header. There are two kinds of token:
1. Firebase JWT (portal-managed)
When you’re signed in to portal.scrapewise.ai , the portal automatically attaches a Firebase JWT to every API call. You don’t see or handle this token directly — it’s refreshed by Firebase Auth in the background.
When to use: when your code runs in a browser context where the user has signed in to the portal. The token is short-lived (~1 hour) and auto-refreshes.
You generally don’t write code that uses JWTs directly — the portal handles it. JWTs are mentioned here so you understand what’s happening when you look at network requests in the portal.
2. API key — sw_live_<prefix>.<secret>
A long-lived bearer token you mint yourself and use from any code that can make HTTPS calls.
When to use: server-side code, CLI scripts, CI pipelines, Claude Desktop / MCP clients — anywhere the portal isn’t running. Most integrations use this.
The format:
sw_live_abc1234.<long random secret>
└────┬────┘└──┬─┘ └────────┬────────┘
env tag prefix secretsw_live_— environment marker. Identifies this as a production key.abc1234— the prefix (7 chars). Visible in the portal, used for identification + audit logging. Not secret.<long random secret>— the actual secret. ~32 random chars. Only shown once at mint time; the platform stores only its hash.
You attach the entire string as a Bearer token:
curl -H "Authorization: Bearer sw_live_abc1234.<your-secret-here>" \
https://portal.scrapewise.ai/api/scraper-api/api/key/whoamiWhich one to use
| Scenario | Method |
|---|---|
| Code in the portal frontend | Firebase JWT (auto) |
| Server-side integration / cron job | API key |
| Claude Desktop / Claude Code / claude.ai | API key (specifically LLM_READ or LLM_FULL scope) |
| CI/CD pipeline | API key |
| Jupyter notebook / quick experiments | API key |
Identifying yourself — whoami
Regardless of which method you use, GET /api/key/whoami returns who Scrapewise sees you as:
curl -H "Authorization: Bearer <token>" \
https://portal.scrapewise.ai/api/scraper-api/api/key/whoamiResponse:
{
"customerRef": "...",
"scope": "USER",
"prefix": "abc1234",
"name": "my-laptop"
}customerRef— your tenant identifierscope— what this token is allowed to do (see Scopes)prefix— for API keys, the 7-char prefix. For JWTs, this is empty.name— your label for the key (or your user identity for JWTs)
Where to put the token
Always in the Authorization: Bearer ... HTTP header. Never:
- In a query string (logged by proxies)
- In a cookie (not how the API auth works)
- In the request body (ignored)