diff --git a/docs/handler/auth.md b/docs/handler/auth.md
index a07dcef..224f83c 100644
--- a/docs/handler/auth.md
+++ b/docs/handler/auth.md
@@ -8,14 +8,16 @@
 h := &handler.AuthHandler{
     Users:               userStore,
     JWT:                 jwtMgr,
-    CookieName:          "session",
-    SecureCookies:       true,
     DisableSignup:       false,    // set true to prevent self-registration
-    Sessions:            sessionStore, // optional; enables session tracking and refresh tokens
-    RefreshTokenTTL:     handler.DefaultRefreshTokenTTL, // defaults to 7 days when Sessions is set
-    RefreshCookieName:   "refresh",  // required when Sessions is set; stores refresh token in an HttpOnly cookie
-    RequireVerification: true,       // optional; rejects login for unverified email addresses
+    RequireVerification: true,     // optional; rejects login for unverified email addresses
     // Logger:           nil, // optional; when nil, slog.Default() is resolved at each log site
+    SessionConfig: handler.SessionConfig{
+        CookieName:        "session",
+        SecureCookies:     true,
+        Sessions:          sessionStore, // optional; enables session tracking and refresh tokens
+        RefreshTokenTTL:   handler.DefaultRefreshTokenTTL, // defaults to 7 days when Sessions is set
+        RefreshCookieName: "refresh",   // required when Sessions is set
+    },
 }
 
 if err := h.Validate(); err != nil {
diff --git a/docs/handler/magic-links.md b/docs/handler/magic-links.md
index f67617a..e03dfe6 100644
--- a/docs/handler/magic-links.md
+++ b/docs/handler/magic-links.md
@@ -6,20 +6,22 @@
 
 ```go
 h := &handler.MagicLinkHandler{
-    Users:             userStore,
-    MagicLinks:        magicLinkStore,
-    JWT:               jwtMgr,
-    Sender:            func(ctx context.Context, email, token string) error {
+    Users:      userStore,
+    MagicLinks: magicLinkStore,
+    JWT:        jwtMgr,
+    Sender: func(ctx context.Context, email, token string) error {
         /* compose and send the login email */
         return nil
     },
-    CookieName:        "session",
-    SecureCookies:     true,
-    Sessions:          sessionStore,      // optional
-    RefreshTokenTTL:   handler.DefaultRefreshTokenTTL, // default 7 days
-    RefreshCookieName: "refresh",
-    TokenTTL:          15 * time.Minute,  // optional; defaults to 15 minutes
-    // Logger:         nil, // optional; when nil, slog.Default() is resolved at each log site
+    TokenTTL: 15 * time.Minute, // optional; defaults to 15 minutes
+    // Logger: nil, // optional; when nil, slog.Default() is resolved at each log site
+    SessionConfig: handler.SessionConfig{
+        CookieName:        "session",
+        SecureCookies:     true,
+        Sessions:          sessionStore,      // optional
+        RefreshTokenTTL:   handler.DefaultRefreshTokenTTL, // default 7 days
+        RefreshCookieName: "refresh",
+    },
 }
 
 if err := h.Validate(); err != nil {
diff --git a/docs/handler/oauth2.md b/docs/handler/oauth2.md
index e874315..274c602 100644
--- a/docs/handler/oauth2.md
+++ b/docs/handler/oauth2.md
@@ -83,18 +83,17 @@ h := &handler.OAuth2Handler{
         Endpoint:     github.Endpoint, // from golang.org/x/oauth2/github
         Scopes:       []string{"read:user", "user:email"},
     },
-    Provider:      &handler.GitHubProvider{},
-    CookieName:    "session",
-    SecureCookies: true,
-
-    // Optional: enable server-side sessions and refresh-token rotation.
-    Sessions:          sessionStore,
-    RefreshTokenTTL:   handler.DefaultRefreshTokenTTL,
-    RefreshCookieName: "refresh",
-
+    Provider: &handler.GitHubProvider{},
+    SessionConfig: handler.SessionConfig{
+        CookieName:    "session",
+        SecureCookies: true,
+        // Optional: enable server-side sessions and refresh-token rotation.
+        Sessions:          sessionStore,
+        RefreshTokenTTL:   handler.DefaultRefreshTokenTTL,
+        RefreshCookieName: "refresh",
+    },
     // Optional: customise the post-login redirect query parameter.
     LoginRedirect: "github_login=1", // redirects to /?github_login=1
-
     // Logger:      nil, // optional; when nil, slog.Default() is resolved at each log site
 }
 
diff --git a/docs/handler/passkeys.md b/docs/handler/passkeys.md
index 3d617fd..8325858 100644
--- a/docs/handler/passkeys.md
+++ b/docs/handler/passkeys.md
@@ -12,18 +12,20 @@ wa, err := webauthn.New(&webauthn.Config{
 })
 
 h := &handler.PasskeyHandler{
-    Users:         userStore,
-    Passkeys:      passkeyStore,
-    WebAuthn:      wa,         // set to nil to disable passkeys
-    JWT:           jwtMgr,
-    CookieName:    "session",
-    SecureCookies: true,
-    URLParamFunc:  chi.URLParam,
-    // Optional: enable session tracking and refresh-token rotation.
-    Sessions:          sessionStore,
-    RefreshTokenTTL:   handler.DefaultRefreshTokenTTL, // default 7 days
-    RefreshCookieName: "refresh",
-    // Logger:         nil, // optional; when nil, slog.Default() is resolved at each log site
+    Users:        userStore,
+    Passkeys:     passkeyStore,
+    WebAuthn:     wa,         // set to nil to disable passkeys
+    JWT:          jwtMgr,
+    URLParamFunc: chi.URLParam,
+    // Logger:    nil, // optional; when nil, slog.Default() is resolved at each log site
+    SessionConfig: handler.SessionConfig{
+        CookieName:    "session",
+        SecureCookies: true,
+        // Optional: enable session tracking and refresh-token rotation.
+        Sessions:          sessionStore,
+        RefreshTokenTTL:   handler.DefaultRefreshTokenTTL, // default 7 days
+        RefreshCookieName: "refresh",
+    },
 }
 
 if err := h.Validate(); err != nil {
diff --git a/docs/index.md b/docs/index.md
index dc15ade..a3b3fd3 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -34,13 +34,15 @@ jwtMgr, err := auth.NewJWTManager("your-secret-at-least-32-bytes-long", 15*time.
 
 // 3. Wire up handlers.
 authHandler := &handler.AuthHandler{
-    Users:             userStore,
-    JWT:               jwtMgr,
-    CookieName:        "session",
-    SecureCookies:     true,
-    Sessions:          sessionStore,      // enables server-side sessions + refresh tokens
-    RefreshTokenTTL:   7 * 24 * time.Hour,
-    RefreshCookieName: "refresh",         // required when Sessions is set
+    Users: userStore,
+    JWT:   jwtMgr,
+    SessionConfig: handler.SessionConfig{
+        CookieName:        "session",
+        SecureCookies:     true,
+        Sessions:          sessionStore,      // enables server-side sessions + refresh tokens
+        RefreshTokenTTL:   7 * 24 * time.Hour,
+        RefreshCookieName: "refresh",         // required when Sessions is set
+    },
 }
 apiKeyHandler := &handler.APIKeyHandler{
     APIKeys:      apiKeyStore,
diff --git a/docs/tutorial.md b/docs/tutorial.md
index b455909..0d4fda8 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -299,13 +299,15 @@ func main() {
 
     // 3. Configure the AuthHandler.
     authH := &handler.AuthHandler{
-        Users:             users,
-        JWT:               jwtMgr,
-        CookieName:        "session",
-        SecureCookies:     false, // set true in production (HTTPS only)
-        Sessions:          sessions,
-        RefreshTokenTTL:   7 * 24 * time.Hour,
-        RefreshCookieName: "refresh",
+        Users: users,
+        JWT:   jwtMgr,
+        SessionConfig: handler.SessionConfig{
+            CookieName:        "session",
+            SecureCookies:     false, // set true in production (HTTPS only)
+            Sessions:          sessions,
+            RefreshTokenTTL:   7 * 24 * time.Hour,
+            RefreshCookieName: "refresh",
+        },
     }
     if err := authH.Validate(); err != nil {
         log.Fatal("authH:", err)
@@ -330,7 +332,7 @@ func main() {
 
     // 5. Start the maintenance background worker.
     ctx := context.Background()
-    stop := maintenance.StartCleanup(ctx, 10*time.Minute,
+    stop := maintenance.StartCleanup(ctx, nil, 10*time.Minute,
         sessions.DeleteExpiredSessions,
     )
     defer stop()