Update API and proxy docs

2026-08-10 21:35:46 +00:00
parent 6f5287e070
commit 00ef0ae2e7
15 changed files with 1107 additions and 123 deletions
@@ -0,0 +1,47 @@
+# The max_age argument
+
+[API overview](../API.md) · [`/auth/api/validate`](validate.md) · [`/auth/api/forward`](../forward.md)
+
+The max_age argument is used by endpoints that validate sessions to require a recent passkey use. It is supported by:
+
+- [POST /auth/api/validate](validate.md)
+- [GET /auth/api/forward](forward.md)
+
+## What it checks
+
+max_age limits how long ago the user last authenticated with their passkey. It is intended for high-risk actions where you want to be sure the user recently proved possession of their credential, not just that they still have a valid session cookie.
+
+The check compares the elapsed time since the credential was last used against the given limit:
+
+- If the credential has a last_used timestamp, that time is used.
+- Otherwise, the session's validated timestamp is used as a fallback.
+
+If the authentication is older than max_age, the endpoint returns 401 with mode reauth, prompting the user to re-authenticate.
+
+## Time units
+
+max_age accepts a number followed by one of these units:
+
+| Unit | Meaning |
+|---|---|
+| s | seconds |
+| m / min | minutes |
+| h | hours |
+| d | days |
+
+Examples:
+
+```text
+?max_age=30s
+?max_age=5m
+?max_age=5min
+?max_age=1h
+?max_age=1d
+```
+
+An invalid format is logged as a warning but does not cause the request to fail; the requirement is simply ignored in that case.
+
+## Important notes
+
+- Session renewal by /auth/api/validate does **not** count as fresh authentication. The check is based on the credential's last_used time, not on how recently the session cookie was renewed.
+- max_age is independent of perm. You can use either or both at the same time.