48 lines
1.6 KiB
Markdown
48 lines
1.6 KiB
Markdown
# 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.
|