CSRF Protection
How the kit stops other sites from making changes with a signed-in user's cookies, and how to allow webhooks.
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.
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
Originheader that differs from the request URL's origin (scheme, host and port), includingOrigin: 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):
export const securityConfig = { // … crossSiteApiPaths: ['/api/webhooks/stripe'],} satisfies SecurityConfig;- Entries are path prefixes matched on whole segments:
/api/webhooksallows/api/webhooks/stripebut 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
GEThandler that changes data (GET /api/unsubscribe?id=…) is open to any site: an<img>tag is enough. UsePOSTfor 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/corsper 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 →