diff --git a/docs/configuration/README.md b/docs/configuration/README.md
index 761ca5c..e4506f7 100644
--- a/docs/configuration/README.md
+++ b/docs/configuration/README.md
@@ -22,6 +22,8 @@ You can see the list of supported environment variables in the [🦀 src/entity/
 > [!WARNING]
 > The static configuration contains an `initial_global_config` key, which is used to populate the bot's global configuration (stored as [dynamic configuration](#dynamic-configuration)) the first time the bot starts. Modifying this subsequently will not have any effect. After initial global configuration creation, it's expected to be managed dynamically via chat commands.
 
+For Matrix-account authentication setup, see [🔐 Authentication](./authentication.md).
+
 
 ### Dynamic configuration
 
diff --git a/docs/configuration/authentication.md b/docs/configuration/authentication.md
new file mode 100644
index 0000000..1048123
--- /dev/null
+++ b/docs/configuration/authentication.md
@@ -0,0 +1,23 @@
+## 🔐 Authentication
+
+baibot supports 2 authentication modes for the Matrix account (`user.*` keys in config).
+
+Set **exactly one** mode. If both are set (or neither is set), startup validation fails.
+
+### Password authentication
+
+- Config key: `user.password`
+- Environment variable: `BAIBOT_USER_PASSWORD`
+
+### Access token authentication
+
+- Config keys: `user.access_token` + `user.device_id`
+- Environment variables: `BAIBOT_USER_ACCESS_TOKEN` + `BAIBOT_USER_DEVICE_ID`
+
+Access-token authentication is useful for OIDC-enabled homeservers (e.g. those using [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service)).
+
+Example token-generation command:
+
+```sh
+mas-cli manage issue-compatibility-token <username> [device_id]
+```
diff --git a/etc/app/config.yml.dist b/etc/app/config.yml.dist
index 1742d7b..007e14d 100644
--- a/etc/app/config.yml.dist
+++ b/etc/app/config.yml.dist
@@ -11,7 +11,7 @@ user:
   # Password-based login (traditional homeservers):
   password: baibot
 
-  # Access token login (for MAS/OIDC-enabled homeservers):
+  # Access token login (for Matrix Authentication Service/OIDC-enabled homeservers):
   # Generate a token via: mas-cli manage issue-compatibility-token <username> [device_id]
   # access_token: null
   # device_id: null