diff --git a/docs/api/README.md b/docs/api/README.md
index 5385d3a0..84edb6c3 100644
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -10,8 +10,11 @@ approval, contact moderation) are deliberately excluded from this API.
 * **Versioning:** path-based (`/api/v1`). Breaking changes will ship a
   `/api/v2` rather than mutate `/api/v1`.
 * **Auth:** opaque bearer tokens (`Authorization: Bearer mwp_...`).
-  Tokens are issued at `POST /api/v1/auth/tokens` and never leak the
-  user's password to API clients.
+  The easiest way to mint a token is from your
+  [account settings page](/users/settings#api-tokens) — log in, scroll
+  to **API tokens**, name it, and copy the value (shown once). You can
+  also mint one programmatically at `POST /api/v1/auth/tokens`. Either
+  way, your password is never sent to API clients.
 * **Format:** `application/json` for requests and successful responses;
   errors use [RFC 9457 problem+json](https://www.rfc-editor.org/rfc/rfc9457).
 * **OpenAPI 3.1 spec:** [`openapi.yaml`](/docs/api/openapi.yaml).
@@ -112,6 +115,10 @@ Defaults:
 
 ### `POST /auth/tokens` — issue an API token
 
+Prefer the [account settings page](/users/settings#api-tokens) for
+interactive use; this endpoint is here for scripts and CLI tools that
+need to mint a token without leaving the terminal.
+
 Request:
 
 ```json