Files
devplacepy/devplacepy/docs_api/groups/auth.py
T
retoor dbdd0d29dd Auth: username+password, email+password and API key everywhere; key returns carry username and email
POST /auth/login (form and JSON) now accepts the username in the email field, like HTTP Basic and POST /auth/token always did; the token endpoint no longer lowercases the identifier before the username lookup, fixing mixed-case usernames. The login field is relabelled and type=text so browsers accept a username.

Every JSON return of the personal API key now also returns the account username and email: the profile JSON gains a can_view_api_key-gated email beside api_key (username already rides profile_user), and POST /profile/regenerate-api-key returns {api_key, username, email}. A client holding only its DEVPLACE_API_KEY value can now fetch its full account via GET /profile in one call.

Documented fully: authentication prose page (three credentials, precedence, DEVPLACE_API_KEY, account fetch, separate DevRant/WebSocket auth domains), new auth-token docs_api card, regenerated-key sample, conventions, README, CLAUDE.md, OpenAPI description, corrected profile key hint. Summary in changes.md (left unversioned per request).

Tests: username/mixed-case/uppercase-email login and token cases, API-key account fetch via X-API-KEY and Bearer, owner/admin vs stranger/guest email gating, regenerate shape, browser login by username. Failing-first observed red, green after.
2026-11-11 16:07:43 +01:00

203 lines
9.4 KiB
Python

# retoor <retoor@molodetz.nl>
from .._shared import endpoint, field
GROUP = {
"slug": "auth",
"title": "Authentication",
"intro": """
# Authentication
Create an account, sign in, recover your password, and log out. These are the only endpoints
that set or clear the `session` cookie; every other request authenticates with the methods
described in [Authentication](/docs/authentication.html). The shared rules (content
negotiation, pagination, status codes) live in [Conventions and Errors](/docs/conventions.html).
## Page vs. action
The GET endpoints render HTML sign-up, login, and password-reset forms; they also return the
page data as JSON when requested with `Accept: application/json` (including `page` to
distinguish the form type).
The POST endpoints are **actions**: they accept form fields, set or clear the `session` cookie,
and return a `302` redirect (or the JSON envelope for JSON callers).
**Sign-up requires a unique `username` and `email`** plus a `confirm_password` that matches the
password; **you log in with your `username` or your `email`, plus your password** (the `email`
field accepts either identifier; usernames are case-sensitive, email addresses are not). The
same identifier rule applies to `POST /auth/token` and HTTP Basic. JSON callers receive
validation errors as a `422` with the shape `{ "fields": {...}, "messages": [...] }`.
""",
"endpoints": [
endpoint(
id="auth-signup",
method="GET",
path="/auth/signup",
title="Sign up page",
summary="Render the registration form. Returns an HTML page.",
auth="public",
interactive=True,
),
endpoint(
id="auth-signup-post",
method="POST",
path="/auth/signup",
title="Sign up",
summary="Create a new account. Sets the session cookie on success.",
auth="public",
encoding="form",
destructive=False,
params=[
field("username", "form", "string", True, "alice", "Username, 3-32 characters (letters, numbers, hyphens, underscores)."),
field("email", "form", "string", True, "alice@example.com", "Email address; must be unique and contain an @."),
field("password", "form", "string", True, "mysecret", "Password, 6+ characters."),
field("confirm_password", "form", "string", True, "mysecret", "Must match password."),
field("birth_date", "form", "string", True, "01/01/1990", "Date of birth, DD/MM/YYYY or YYYY-MM-DD. Only the derived age band is stored; the date is discarded."),
field("accept_terms", "form", "enum", True, "1", "Acceptance of the Terms of Service and Community Guidelines.", ["1"]),
],
notes=[
"Signup is refused below the platform minimum age (`moderation_minimum_age`).",
"Accepting records the terms, privacy and activity-recording consents; "
"third-party AI processing stays off until it is granted separately.",
"JSON callers receive the new account's `email`, `api_key`, and "
"`is_admin` flag in `data`, so a script can authenticate its next "
"request immediately.",
],
sample_response={
"ok": True,
"redirect": "/feed",
"data": {
"username": "alice",
"email": "alice@example.com",
"api_key": "API_KEY",
"is_admin": False,
},
},
),
endpoint(
id="auth-login",
method="GET",
path="/auth/login",
title="Log in page",
summary="Render the login form. Returns an HTML page.",
auth="public",
interactive=True,
params=[
field("next", "query", "string", False, "", "Redirect target after login."),
],
),
endpoint(
id="auth-login-post",
method="POST",
path="/auth/login",
title="Log in",
summary="Authenticate with username (or email) and password. Sets the session cookie.",
auth="public",
encoding="form",
params=[
field("email", "form", "string", True, "alice@example.com", "Your username or your registered email."),
field("password", "form", "string", True, "mysecret", "Your password."),
field("remember_me", "form", "string", False, "on", "Send 'on' to extend the session to the remember-me lifetime."),
field("next", "form", "string", False, "", "Redirect target after login."),
],
notes=[
"JSON callers receive the account's `username`, `email`, `api_key`, "
"and `is_admin` flag in `data`, so a script can trade one "
"username/password or email/password login for a reusable key. "
"Failed logins return 401 and never include the key.",
],
sample_response={
"ok": True,
"redirect": "/feed",
"data": {
"username": "alice",
"email": "alice@example.com",
"api_key": "API_KEY",
"is_admin": False,
},
},
),
endpoint(
id="auth-token",
method="POST",
path="/auth/token",
title="Issue access token",
summary="Exchange username (or email) and password for a short-lived access token. No session cookie is set.",
auth="public",
encoding="form",
params=[
field("email", "form", "string", True, "alice@example.com", "Your username or your registered email."),
field("password", "form", "string", True, "mysecret", "Your password."),
],
notes=[
"Accepts a JSON body with the same fields. The returned token "
"works as an `Authorization: Bearer` or `X-API-KEY` credential "
"until it expires (default 7 days). Missing fields return 400, "
"wrong credentials 401, a deactivated account 403; failures "
"never include a token.",
],
sample_response={
"access_token": "ACCESS_TOKEN",
"token_type": "bearer",
"expires_in": 604800,
},
),
endpoint(
id="auth-forgot-password",
method="GET",
path="/auth/forgot-password",
title="Forgot password page",
summary="Render the forgot-password form. Returns an HTML page.",
auth="public",
interactive=True,
),
endpoint(
id="auth-forgot-password-post",
method="POST",
path="/auth/forgot-password",
title="Request password reset",
summary="Send a password-reset email with a one-time link.",
auth="public",
encoding="form",
params=[
field("email", "form", "string", True, "alice@example.com", "Your registered email."),
],
),
endpoint(
id="auth-reset-password",
method="GET",
path="/auth/reset-password/{token}",
title="Reset password page",
summary="Render the password-reset form (only valid with a one-time token). Returns an HTML page.",
auth="public",
interactive=True,
params=[
field("token", "path", "string", True, "RESET_TOKEN", "The one-time reset token from the email."),
],
),
endpoint(
id="auth-reset-password-post",
method="POST",
path="/auth/reset-password/{token}",
title="Reset password",
summary="Set a new password using a one-time reset token.",
auth="public",
encoding="form",
params=[
field("token", "path", "string", True, "RESET_TOKEN", "The one-time reset token from the email."),
field("password", "form", "string", True, "newpass", "New password, 6+ characters."),
field("confirm_password", "form", "string", True, "newpass", "Must match password."),
],
),
endpoint(
id="auth-logout",
method="GET",
path="/auth/logout",
title="Log out",
summary="Clear the session cookie and redirect to the landing page.",
auth="public",
interactive=False,
),
],
}