From 4d08994e79da12fd39ccd00d042dd4cb2e728d95 Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Sat, 25 Apr 2026 12:34:55 -0400 Subject: [PATCH] docs: sync updated frontend API guide for user auth endpoints Co-Authored-By: Claude Sonnet 4.6 --- documentation/GUIDE__AE_API_V3_for_Frontend.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/documentation/GUIDE__AE_API_V3_for_Frontend.md b/documentation/GUIDE__AE_API_V3_for_Frontend.md index 5b005a3b..d63c09ea 100644 --- a/documentation/GUIDE__AE_API_V3_for_Frontend.md +++ b/documentation/GUIDE__AE_API_V3_for_Frontend.md @@ -401,7 +401,7 @@ or: **Response on success:** Full user object (same shape as `GET /v3/crud/user/{id}`). -**Errors:** `400` missing credentials, `403` wrong password or account disabled, `404` user not found. +**Errors:** `400` missing credentials, `403` wrong password / account disabled / account not yet enabled / account expired, `404` user not found. > **Auth key flow:** Auth keys are one-time-use — the key is cleared from the DB immediately on successful authentication. Request a new one via `GET /v3/action/user/{id}/new_auth_key`. @@ -421,7 +421,7 @@ Check a user's current password without changing it. ``` or use `"username"` instead of `"user_id"` to look up by username within the account. -**Response:** `data: true` on match. `403` on mismatch, `404` if user not found. +**Response:** `data: true` on match. `400` if the user has no password set, `403` on mismatch, `404` if user not found. --- @@ -474,10 +474,19 @@ Generate a new auth key and email a one-time login link to the user's email addr | Parameter | Type | Default | Description | |---|---|---|---| -| `root_url` | `string` | `null` | Base URL the login link is built from. | +| `root_url` | `string` | *(required)* | Base URL the login link is built from. Must be provided — if omitted the link in the email will be malformed (`None?...`). | | `key_param_name` | `string` | `auth_key` | Query param name used for the auth key in the generated link. | -**Response:** `data: true` on success (email sent). `500` if delivery failed (check account email config and that the user account is enabled with `allow_auth_key = true`). +> [!IMPORTANT] +> `root_url` is **required in practice**. The FastAPI query param accepts `null` but the email builder does not guard against it — omitting it produces a broken link in the email. + +**Magic link URL format (default `key_param_name`):** +``` +{root_url}?user_id={user_id_random}&auth_key={auth_key}&valid_email=True +``` +The frontend at `root_url` should read these query params and call `POST /v3/action/user/authenticate` with `{ "user_id": "...", "auth_key": "..." }`. Note that `valid_email=True` is **always** injected — authenticating via a magic link automatically marks the user's email as verified. + +**Response:** `data: true` on success (email sent). `404` if user not found. `500` if delivery failed — common causes: account email not configured, user `enable = false`, or `allow_auth_key = false`. ---