Authentication

Scrappycoco accepts workspace API keys and OAuth bearer tokens. Both can
authorize billable scraper requests.

Workspace API keys

Use API keys for application backends, services, and CI. API-key authentication
has no refresh-token rotation step and supports concurrent requests subject to
the workspace and provider concurrency limits.

1. Create and name a key under API Keys in the dashboard.
2. Copy the full key when it is shown; it is displayed once.
3. Store it in a secret manager.
4. Send it in the X-API-Key header.

curl "https://api.scrappycoco.ai/api/v1/me" \
  -H "X-API-Key: $SCRAPPYCOCO_API_KEY"

Name keys by environment and owner so usage remains attributable. Never put a
key in a URL, prompt, source file, browser bundle, or log.

CLI OAuth

Interactive CLI setup uses Authorization Code + PKCE:

npx --yes @scrappycoco/cli@latest auth login
npx --yes @scrappycoco/cli@latest auth status --json
npx --yes @scrappycoco/cli@latest auth logout

The refresh token is stored in the OS keychain when available, with a
permission-restricted local fallback. The CLI refreshes your session automatically.

MCP OAuth

MCP clients connect to https://api.scrappycoco.ai/mcp and follow the server's
OAuth protected-resource metadata. Trust, plugin loading, and OAuth approval
are separate security steps in the host client.

Request attribution

Official clients send a channel identifier (api, mcp, or cli) so usage
can be grouped correctly. API responses never return authentication
credentials or OAuth tokens.