From 076a26dc36ccd7cc4c792f53bd05e5687c487832 Mon Sep 17 00:00:00 2001
From: Jake Howell <jake@hwll.me>
Date: Thu, 16 Jul 2026 13:58:30 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=A4=96=20docs(admin/users):=20document=20?=
 =?UTF-8?q?login=5Ftype=3Dnone=20deprecation=20and=20service-account=20con?=
 =?UTF-8?q?version?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

diff --git a/docs/admin/users/headless-auth.md b/docs/admin/users/headless-auth.md
index e61124b7e5b74..67b199099da07 100644
--- a/docs/admin/users/headless-auth.md
+++ b/docs/admin/users/headless-auth.md
@@ -36,3 +36,49 @@ 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
+
+> [!WARNING]
+> This conversion is irreversible and clears email addresses. Export any email
+> addresses you need to keep before you upgrade.
+
+When you upgrade, Coder converts existing non-system `login_type=none` users
+into service accounts. Service accounts cannot have an email address, so each
+converted user's email is cleared. Existing API tokens for these accounts
+remain valid. System users are not affected.