From 9ce76beefcfab363366549dfbd3fcf19cac9eac8 Mon Sep 17 00:00:00 2001
From: Maxwell <145994855+ping-maxwell@users.noreply.github.com>
Date: Fri, 14 Nov 2025 06:09:06 +1000
Subject: [PATCH] docs: document `oauthConfig` in `options.mdx` (#5947)

---
 docs/content/docs/errors/state_mismatch.mdx | 9 +++++++++
 docs/content/docs/reference/options.mdx     | 7 ++++++-
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/docs/content/docs/errors/state_mismatch.mdx b/docs/content/docs/errors/state_mismatch.mdx
index 5486571a95..2958801e77 100644
--- a/docs/content/docs/errors/state_mismatch.mdx
+++ b/docs/content/docs/errors/state_mismatch.mdx
@@ -34,6 +34,15 @@ same browser session that started it.
 * Check that cookies are not blocked by browser settings or privacy modes.
 * Ensure you're starting and ending the OAuth flow in the same browser session.
 
+### Skip state cookie check
+
+If you know what you are doing, you can skip the state cookie check by
+setting the `advanced.oauthConfig.skipStateCookieCheck` option to `true` in your auth config.
+
+<Callout type="warn">
+  Please note that this is a security risk and should only be enabled if you know what you are doing.
+</Callout>
+
 ### Production Debug
 
 Head to your production site, and use your browser's DevTools → Application → Cookies to confirm:
diff --git a/docs/content/docs/reference/options.mdx b/docs/content/docs/reference/options.mdx
index f765d0f829..4dac01a1da 100644
--- a/docs/content/docs/reference/options.mdx
+++ b/docs/content/docs/reference/options.mdx
@@ -465,6 +465,10 @@ export const auth = betterAuth({
 			httpOnly: true,
 			secure: true
 		},
+		oauthConfig: {
+			skipStateCookieCheck: false,
+			storeStateStrategy: "database"
+		},
 		cookiePrefix: "myapp",
 		database: {
 			// Use your own custom ID generator, disable generating IDS so your database will generate them, or use "serial" to use your database's auto-incrementing ID, or "uuid" to use a random UUID.
@@ -487,7 +491,8 @@ export const auth = betterAuth({
 - `cookies`: Customize cookie names and attributes
 - `defaultCookieAttributes`: Default attributes for all cookies
 - `cookiePrefix`: Prefix for cookies
-- `generateId`: Function to generate a unique ID for a model
+- `database`: Database configuration options
+- `oauthConfig`: OAuth configuration options
 
 ## `logger`