From 6ce234f684cfd91b0f00e51a219b9aab2d787339 Mon Sep 17 00:00:00 2001
From: Jake Howell <jake@hwll.me>
Date: Mon, 20 Jul 2026 03:03:50 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=A4=96=20docs(docs/admin/users):=20docume?=
 =?UTF-8?q?nt=20login=5Ftype=3Dnone=20deprecation=20and=20password=20conve?=
 =?UTF-8?q?rsion?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/admin/users/headless-auth.md | 50 +++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/docs/admin/users/headless-auth.md b/docs/admin/users/headless-auth.md
index e61124b7e5b74..4f95ecba71a2d 100644
--- a/docs/admin/users/headless-auth.md
+++ b/docs/admin/users/headless-auth.md
@@ -36,3 +36,53 @@ Navigate to **Deployment** > **Users** > **Create user**, then select
 
 To make API or CLI requests on behalf of the headless user, learn how to
 [generate API tokens on behalf of a user](./sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-another-user).
+
+## Deprecation of `login_type=none`
+
+Older Coder versions created passwordless machine users with
+`coder users create --login-type none` or the `--disable-login` flag. Creating
+these accounts is no longer supported. Use service accounts for
+machine-to-machine access instead.
+
+Coder rejects these requests at creation:
+
+- `coder users create --login-type none` fails unless you also pass
+  `--service-account`:
+
+  ```text
+  Login type 'none' requires --service-account.
+  ```
+
+- `--disable-login` is rejected:
+
+  ```text
+  --disable-login is deprecated. Use --service-account for machine-to-machine access.
+  ```
+
+- `POST /users` returns `400 Bad Request` for `login_type: "none"` without a
+  service account:
+
+  ```text
+  Login type 'none' requires a service account.
+  ```
+
+Service accounts require a [Premium license](https://coder.com/pricing). On
+OSS deployments, create a regular user with password, GitHub, or OIDC
+authentication for automation instead. See
+[Test templates through CI/CD](../../tutorials/testing-templates.md) for an
+example.
+
+### Upgrade behavior
+
+When you upgrade, Coder converts existing non-system `login_type=none` users to
+password authentication (`login_type=password`). Their email addresses and
+existing API tokens are **preserved**, so token-based automation keeps working
+unchanged. System users are not affected.
+
+These accounts have no password set, so an admin must
+[reset the password](./index.md#reset-a-password) before the account can log in
+through the web UI. Machine access through existing tokens is unaffected.
+
+> [!NOTE]
+> This conversion is one-way. Coder does not record which users previously had
+> `login_type=none`, so a downgrade cannot restore it.