# CSRF Protection

> How the kit stops other sites from making changes with a signed-in user's cookies, and how to allow webhooks.

*Canonical: https://makerkit.dev/docs/void-cloudflare/security/csrf*

---

Another site can make a signed-in user's browser send requests to your app, cookies included (cross-site request forgery). The kit rejects those requests before any handler runs.

This page is part of the [Security documentation](./overview).

## What Is Protected

| Request | Protected by | Response when cross-site |
|---|---|---|
| Page actions (`Form`, `useForm`, `action` in `*.server.ts`) | Void itself | `403 Forbidden` |
| `POST`, `PUT`, `PATCH`, `DELETE` to `/api/*` | `apps/web/middleware/04.api-origin.ts` (kit-owned) | `403 { "error": "Forbidden" }` |
| `/api/auth/*` (Better Auth) | Better Auth's trusted origins | Better Auth's own response |
| `GET`, `HEAD`, `OPTIONS` to `/api/*` | Nothing: they must not change data | Passes |

## How the Check Works

A write to `/api/*` is rejected when either:

- the browser says `Sec-Fetch-Site: cross-site`, or
- it sends an `Origin` header that differs from the request URL's origin (scheme, host and port), including `Origin: null`.

Same-origin is the URL the request arrived at, never `SITE_URL` or `X-Forwarded-*` headers. So custom domains, `workers.dev` and preview URLs all work without configuration.

Requests with neither header pass: they come from curl, other servers or webhooks, not from a browser carrying a user's cookies. **They still reach your handler unauthenticated**, so every handler must check the session (or a signature) itself.

## Allowing a Webhook

Payment providers and other services post to your app from their own servers. Most send no `Origin` and pass already. If one sends browser-like headers, allow its path in `apps/web/config/security.config.ts` (yours to edit):

```ts
export const securityConfig = {
  // …
  crossSiteApiPaths: ['/api/webhooks/stripe'],
} satisfies SecurityConfig;
```

- Entries are path prefixes matched on whole segments: `/api/webhooks` allows `/api/webhooks/stripe` but not `/api/webhooks-old`.
- An allowed path accepts writes from any site, so its handler must verify the provider's signature before doing anything.
- Don't allow a path that relies on the user's session cookie.

## Common Pitfalls

- **A `GET` handler that changes data** (`GET /api/unsubscribe?id=…`) is open to any site: an `<img>` tag is enough. Use `POST` for changes.
- **Calling your API from another frontend** (a separate marketing site, a mobile web view on another origin) gets 403. Serve it from the same origin, or give that endpoint its own token-based auth and allowlist the path.
- **CORS doesn't replace this check.** CORS controls who can read a response; a cross-site form post is sent without asking. Add `hono/cors` per handler only for public read APIs.
- **Relying on the check for authorization:** it only stops other sites. A signed-in user calling your API directly passes, so authorize inside every handler.

---

**Next:** [Coding Agents →](./coding-agents)
