> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shopsniffer.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

The three ways to authenticate with the ShopSniffer API — API keys, Better Auth sessions, and x402 payment for account-free access.

## 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](https://shopsniffer.com/dashboard), 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](https://www.better-auth.com) 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](/x402-payment) and the [x402 tutorial](/guides/pay-with-x402) 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

**[API reference](/api)**

Complete endpoint reference organized by resource.
  **[Rate limits](/rate-limits)**

Per-minute and per-day limits for authenticated and anonymous requests.
  **[x402 payment](/x402-payment)**

Pay per request without an account.
  **[Buying a report](/buying-a-report)**

Stripe and crypto payment flows for one-off reports.