serverpod · FXschwartz · Sep 10, 2026 · Sep 8, 2026 · Sep 8, 2026 · Sep 8, 2026
diff --git a/docs/06-concepts/03-data-and-the-database/02-database/13-migrations.md b/docs/06-concepts/03-data-and-the-database/02-database/13-migrations.md
@@ -57,7 +57,7 @@ $ serverpod create-migration --empty
 
 ### Tag migration
 
-Tags can be useful to identify migrations that introduced specific changes to the project. Tags are appended to the migration name and can be added with the `--tag` option.
+Tags can be useful to identify migrations that introduced specific changes to the project. Tags are appended to the migration name and can be added with the `--tag` option. A tag can contain only lowercase letters, numbers, and dashes.
 
 ```bash
 $ serverpod create-migration --tag "v1-0-0"

diff --git a/docs/06-concepts/04-authentication/10-web-authentication.md b/docs/06-concepts/04-authentication/10-web-authentication.md
@@ -20,14 +20,16 @@ Enable cookie auth by adding an `authCookie` section to your server configuratio
 
 ```yaml
 authCookie:
-  # secure: false # Uncomment only for http://localhost development.
+  sameSite: lax
 allowedOrigins:
   - https://app.example.com
 ```
 
+For local development, use `secure: false` in `config/development.yaml` so the cookie is sent over `http://localhost`. The section must contain at least one field: an `authCookie:` key with no children is read as unset, and cookie auth stays off.
+
 `allowedOrigins` is required when `authCookie` is set: it backs the CSRF origin checks and credentialed CORS, which cannot use a wildcard origin. List every browser origin that calls your server. With cookie auth enabled, browsers on origins that are not in the list lose cross-origin access, including to public endpoints.
 
-All `authCookie` fields are optional:
+Each field and its default:
 
 | Field         | Default                  | Purpose                                                        |
 | ------------- | ------------------------ | -------------------------------------------------------------- |
@@ -62,7 +64,7 @@ Everything else is unchanged: sign-in flows, the `client.auth` session manager,
 3. Confirm no token appears in **Local Storage** for your app's origin.
 4. Reload the page. The user is still signed in.
 
-If sign-in fails, check that every browser origin is listed in `allowedOrigins`, and on `http://localhost` that `authCookie.secure` is `false`.
+If sign-in fails, check that every browser origin is listed in `allowedOrigins`, and on `http://localhost` that `authCookie.secure` is `false`. If the app throws `StateError: cookieAuth is enabled but the server returned the auth token in the response body`, the server's `authCookie` section is missing or has no fields; add at least one.
 
 ## How it works
 

diff --git a/docs/06-concepts/07-operations/06-scalability.md b/docs/06-concepts/07-operations/06-scalability.md
@@ -105,7 +105,7 @@ Keep `websocketPingInterval` (default 30 seconds) in mind under high connection
 | --- | --- | --- |
 | `role` / `SERVERPOD_SERVER_ROLE` | `monolith` | Split request nodes from maintenance work. |
 | `database.maxConnectionCount` | `10` | Pool size times node count must fit Postgres. |
-| `redis.enabled` | `false` | Required for shared cache and global events. |
+| `redis.enabled` | `true` when a `redis` section is present | Required for shared cache and global events. |
 | `maxRequestSize` | `524288` | Large uploads increase memory pressure. |
 | `websocketPingInterval` | `30` (seconds) | Keepalive cost under many open streams. |
 | `futureCall.concurrencyLimit` | `1` | Caps background CPU and database load. |

diff --git a/docs/06-concepts/cli/commands/create-migration/_create-migration.md b/docs/06-concepts/cli/commands/create-migration/_create-migration.md
@@ -2,4 +2,4 @@
 
 The `serverpod create-migration` command compares your current models and database definition to the last migration and writes a new migration for the difference. Run it after changing your model files.
 
-Use `--force` to proceed when a change may drop data, `--tag` to label the revision, or `--empty` to create a migration even when nothing has changed. For the full workflow, see [Migrations](../../data-and-the-database/database/migrations).
+Use `--force` to proceed when a change may drop data, `--tag` to label the revision (lowercase letters, numbers, and dashes only), or `--empty` to create a migration even when nothing has changed. For the full workflow, see [Migrations](../../data-and-the-database/database/migrations).
diff --git a/docs/06-concepts/lookups/configuration-reference.md b/docs/06-concepts/lookups/configuration-reference.md
@@ -55,10 +55,17 @@ Ports, hosts, and connection settings for the API, Insights, and web servers, th
 | SERVERPOD_REDIS_HOST                             | redis.host                          | -         | The host address of the Redis server                                                                                                                                                                         |
 | SERVERPOD_REDIS_PORT                             | redis.port                          | -         | The port number for the Redis server                                                                                                                                                                         |
 | SERVERPOD_REDIS_USER                             | redis.user                          | -         | The user name for Redis authentication                                                                                                                                                                       |
-| SERVERPOD_REDIS_ENABLED                          | redis.enabled                       | false     | Indicates if Redis is enabled                                                                                                                                                                                |
+| SERVERPOD_REDIS_ENABLED                          | redis.enabled                       | true      | Indicates if Redis is enabled. Defaults to `true` when a `redis` section is present; Redis is off when the section is absent or `enabled` is `false`.                                                        |
 | SERVERPOD_REDIS_REQUIRE_SSL                      | redis.requireSsl                    | false     | Indicates if SSL is required for the Redis connection                                                                                                                                                        |
 | SERVERPOD_MAX_REQUEST_SIZE                       | maxRequestSize                      | 524288    | The maximum size of API requests in bytes. Also caps file uploads that post to the API server.                                                                                                                |
 | SERVERPOD_VALIDATE_HEADERS                       | validateHeaders                     | true      | Validate HTTP headers using the typed API. Set to `false` to accept headers without the required formatting, for example an unwrapped token in the Authorization header.                                     |
+| SERVERPOD_ALLOWED_ORIGINS                        | allowedOrigins                      | -         | Browser origins allowed to make credentialed cross-origin calls, as `scheme://host[:port]`. A YAML list, or comma-separated in the environment variable. Required when `authCookie` is set. See [Web authentication](../authentication/web-authentication).|
+| SERVERPOD_AUTH_COOKIE_NAME                       | authCookie.name                     | -         | Name of the auth cookie. Defaults to `serverpod_auth`. Setting any `authCookie` field enables cookie auth for web clients; an empty `authCookie` section is read as unset.                                   |
+| SERVERPOD_AUTH_COOKIE_REFRESH_NAME               | authCookie.refreshName              | -         | Name of the JWT refresh cookie. Defaults to `<name>_refresh`.                                                                                                                                                |
+| SERVERPOD_AUTH_COOKIE_DOMAIN                     | authCookie.domain                   | -         | Cookie `Domain` attribute. Defaults to host-only; set to share the cookie across subdomains.                                                                                                                 |
+| SERVERPOD_AUTH_COOKIE_PATH                       | authCookie.path                     | /         | Cookie `Path` attribute.                                                                                                                                                                                     |
+| SERVERPOD_AUTH_COOKIE_SECURE                     | authCookie.secure                   | true      | Whether the cookie is only sent over https. Set to `false` only for `http://localhost` development.                                                                                                          |
+| SERVERPOD_AUTH_COOKIE_SAME_SITE                  | authCookie.sameSite                 | lax       | Cookie `SameSite` attribute. Valid options are `lax`, `strict`, and `none` (`none` requires `secure`).                                                                                                       |
 | SERVERPOD_SESSION_PERSISTENT_LOG_ENABLED         | sessionLogs.persistentEnabled       | -         | Enables or disables logging session data to the database. Defaults to `true` if a database is configured, otherwise `false`.                                                                                 |
 | SERVERPOD_SESSION_LOG_CLEANUP_INTERVAL           | sessionLogs.cleanupInterval         | 24h       | How often to run the log cleanup job. Duration string (e.g. `24h`, `2d`). Set to null to disable automated purging.                                                                                          |
 | SERVERPOD_SESSION_LOG_RETENTION_PERIOD           | sessionLogs.retentionPeriod         | 90d       | How long to keep session log entries. Duration string (e.g. `30d`, `60d`). Set to null to disable time-based cleanup.                                                                                        |

diff --git a/docs/11-upgrading/01-upgrade-to-four.md b/docs/11-upgrading/01-upgrade-to-four.md
@@ -128,7 +128,7 @@ The `hotReload`, `getOpenSessionLog`, and `shutdown` Insights methods are remove
 Version 4.0 adds a few new internal Serverpod tables and updates some indexes to greatly improve logs performance on Insights. Create a migration that captures these schema deltas so your database can be brought up to date:
 
 ```bash
-$ serverpod create-migration --tag "upgrade-4.0"
+$ serverpod create-migration --tag "upgrade-4-0"
 ```
 
 This writes a new migration to `<project>_server/migrations/`. It will be applied to your database in the next step.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,4 +2,4 @@

		The `serverpod create-migration` command compares your current models and database definition to the last migration and writes a new migration for the difference. Run it after changing your model files.

		Use `--force` to proceed when a change may drop data, `--tag` to label the revision, or `--empty` to create a migration even when nothing has changed. For the full workflow, see [Migrations](../../data-and-the-database/database/migrations).
		Use `--force` to proceed when a change may drop data, `--tag` to label the revision (lowercase letters, numbers, and dashes only), or `--empty` to create a migration even when nothing has changed. For the full workflow, see [Migrations](../../data-and-the-database/database/migrations).