website/docs: document account switching

A7k-product: product
A7k-product-repo: 1
Co-authored-by: Agent <claudeagent@svc.sdko.net>

website/docs/sidebar.mjs

@@ -531,6 +531,7 @@ const items = [
                     "users-sources/user/user_ref",
                     "users-sources/user/invitations",
                     "users-sources/user/password_reset_on_login",
+                    "users-sources/user/account-switching",
                     "users-sources/user/user-interface",
                 ],
             },

website/docs/sys-mgmt/brands/index.md

@@ -43,6 +43,7 @@ You can configure authentik to redirect external users to a default application
 You can explicitly select, in your instance's Brand settings, the _default flows_ to use for the current brand. You can optionally configure these default flows ([learn more about each default flow](../../add-secure-apps/flows-stages/flow/examples/default_flows.md)):
 
 - **Authentication** flow: the flow used to authenticate users. If left empty, the first applicable flow sorted by the slug is used.
+- **Account switch flow**: the authentication flow used when [switching between accounts](../../users-sources/user/account-switching.md) signed in on the same browser. If no flow is set, account switching is not offered.
 - **Invalidation flow**: for typical use cases, select the `default-invalidation-flow` (Logout) flow. This flow logs the user out of authentik when the application session ends (user logs out of the app).
 - **Recovery flow**: if set, the user can access an option to recover their login credentials.
 - **Unenrollment flow**: if set, users are able to unenroll themselves using this flow. If no flow is set, option is not shown.

website/docs/users-sources/user/account-switching.md

@@ -0,0 +1,31 @@
+---
+title: Account switching
+---
+
+authentik can keep multiple accounts signed in within the same browser and let users switch between them from the User interface header.
+
+## How it works
+
+Every login creates its own session. authentik groups the sessions created by the same browser using an opaque browser cookie (`authentik_accounts`), so only that browser can switch between them. Only the most recent login is active at a time; switching to another account authenticates that account through a flow, it never silently reuses the previous session.
+
+When a user picks another account from the switcher, authentik checks that the browser holds a live session for that account and starts the configured account switch flow with the following flow context:
+
+- `pending_user`: the account being switched to
+- `account_switch_from_user`: the account that was active when the switch started
+- `is_account_switch`: set to `true`
+
+The previous account's session stays signed in as a switch target, but its session cookie can no longer be used to act as that account.
+
+Logins performed through a switch are recorded in the event log with `is_account_switch` and the user that switched.
+
+## Configuration
+
+Account switching is only offered when the brand has an **Account switch flow** set (under **System** > **Brands**, in the brand's **Default flows**). Any authentication flow can be used.
+
+By default the selected flow runs in full, including identification and password stages. The username of the account being switched to is pre-filled. To let switches skip stages, bind a policy to the stage binding in the flow; the flow context above is available on the policy request. For example, an expression policy that skips its stage during account switches:
+
+```python
+return not request.context.get("is_account_switch", False)
+```
+
+Bind this policy to the identification, password, or authenticator validation stage bindings of the flow, depending on what a switch back to a signed-in account needs to confirm.