Authentication

Overview

ShopSniffer supports three authentication methods. Most read endpoints (job status, reports, free export, public store directory) need no authentication at all. Creating jobs, managing tracked shops, and managing API keys require one of the methods below.

Method matrix

Method	Best for	Header	Required for
API key Stable	Scripts, CI, AI agents	X-API-Key: ss_…	Long-running integrations
Better Auth session Stable	Browser apps	Cookie (auto)	Dashboard, web UI
x402 payment Account-free	One-shot calls, autonomous agents	X-PAYMENT: …	Paying per request without sign-up

API key

Recommended for scripts and AI agents. Create one from your Dashboard → API Keys tab, then pass it via the X-API-Key header. Keys are stored as SHA-256 hashes — the raw key is shown only once at creation.

bash
curl -X POST https://shopsniffer.com/api/jobs \
  -H "X-API-Key: ss_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

Revoke a compromised key immediately via DELETE /api/api-keys/:id. Revocation takes effect on the next request.

Better Auth session

For browser-based integrations. ShopSniffer uses Better Auth with email/password and Google OAuth, mounted at /api/auth. Sign up or sign in on the website and a session cookie is set automatically. Subsequent API calls from the same origin are authenticated by that cookie — no token handling required.

Session cookies are SameSite=Lax and scoped to shopsniffer.com. If you're calling the API from a different origin, use an API key instead.

typescript
// In a browser on shopsniffer.com — the cookie is sent automatically
const res = await fetch("/api/jobs", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ domain: "example.com" }),
});

Server-side auth endpoints (sign up, sign in, sign out, password reset, session refresh) live under /api/auth/* and are managed by Better Auth directly.

x402 payment

Pay per request with USDC on Base. No sign-up required — ideal for one-off reports or autonomous AI agents that need to spend without holding credentials. See x402 payment and the x402 tutorial for the full flow.

Which endpoints need which

Endpoint category	Anonymous	API key / session	x402
GET /api/free-export	✓	✓	—
GET /api/jobs/:id status reports pagespeed changelog	✓	✓	—
GET /api/stores (directory)	✓	✓	—
POST /api/jobs (create report)	—	✓	✓
GET / POST /api/shops (tracking)	—	✓	—
POST / GET / DELETE /api/api-keys	—	Session only	—
GET /api/store-detail/:slug/*	—	Session only	—
POST /api/chat	✓ (stricter limits)	✓	—

Next steps