Clarify __session cookie domain behavior (#2723)

f-westergren · alexisintech · web-flow · commit b4784926d2fb · 2025-10-23T16:31:08.000-04:00
Co-authored-by: Alexis Aguilar &lt;98043211+alexisintech@users.noreply.github.com&gt;
diff --git a/docs/guides/how-clerk-works/overview.mdx b/docs/guides/how-clerk-works/overview.mdx
@@ -285,7 +285,7 @@ When your app makes a request from the frontend to your backend, if the backend
 >
 > Setting cookies as `HttpOnly` is generally recommended to prevent client-side JavaScript access, reducing the risk of cross-site scripting (XSS) attacks. However, due to Clerk's architecture, this approach wouldn't work.
 >
-> Remember that FAPI is hosted on a different origin than your app. Let's say, in production, your app is `example.com`. Then FAPI is `clerk.example.com`. If FAPI set the `__session` cookie as `HttpOnly`, it would be scoped to `clerk.example.com`, preventing it from being sent to `example.com`. Since cookies are only sent to the domain that matches their domain value, which is the domain that sets them, this setup would block your app from accessing the cookie.
+> Remember that FAPI is hosted on a different origin than your app. Let's say, in production, your app is `example.com`. Then FAPI is `clerk.example.com`. Since cookies are only sent to the domain that set them (or its subdomains, depending on the `Domain` attribute), any cookie set by FAPI would be scoped to `clerk.example.com` and would not be sent to `example.com`.
 >
 > To work around this, Clerk returns the session token from FAPI after a user signs in, and the client-side SDK used by your app (e.g., React SDK) sets the `__session` cookie containing the session token on your app's domain **via JavaScript**. A benefit of this is that it allows the token's value and session claims to be accessed on the client-side. This is often quite valuable, as it allows developers to send the session token as a custom header in requests and also makes it possible to use a subdomain (like `api.example.com`) for your backend. However, because it's set client-side, it cannot be `HttpOnly`, making it more vulnerable to XSS attacks.
 >

Original file line number	Diff line number	Diff line change
`@@ -285,7 +285,7 @@ When your app makes a request from the frontend to your backend, if the backend`
`285`	`285`	`>`
`286`	`286`	> Setting cookies as `HttpOnly` is generally recommended to prevent client-side JavaScript access, reducing the risk of cross-site scripting (XSS) attacks. However, due to Clerk's architecture, this approach wouldn't work.
`287`	`287`	`>`
`288`		-> Remember that FAPI is hosted on a different origin than your app. Let's say, in production, your app is `example.com`. Then FAPI is `clerk.example.com`. If FAPI set the `__session` cookie as `HttpOnly`, it would be scoped to `clerk.example.com`, preventing it from being sent to `example.com`. Since cookies are only sent to the domain that matches their domain value, which is the domain that sets them, this setup would block your app from accessing the cookie.
	`288`	+> Remember that FAPI is hosted on a different origin than your app. Let's say, in production, your app is `example.com`. Then FAPI is `clerk.example.com`. Since cookies are only sent to the domain that set them (or its subdomains, depending on the `Domain` attribute), any cookie set by FAPI would be scoped to `clerk.example.com` and would not be sent to `example.com`.
`289`	`289`	`>`
`290`	`290`	> To work around this, Clerk returns the session token from FAPI after a user signs in, and the client-side SDK used by your app (e.g., React SDK) sets the `__session` cookie containing the session token on your app's domain via JavaScript. A benefit of this is that it allows the token's value and session claims to be accessed on the client-side. This is often quite valuable, as it allows developers to send the session token as a custom header in requests and also makes it possible to use a subdomain (like `api.example.com`) for your backend. However, because it's set client-side, it cannot be `HttpOnly`, making it more vulnerable to XSS attacks.
`291`	`291`	`>`