LeoVasanko/paskia
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Add renew=0 query arg on validate, useful when only a permission check is required.

Browse Source
This commit is contained in:
LeoVasanko
2026-08-11 01:46:56 +00:00
parent 2456730f70
commit 223429d51c
5 changed files with 65 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
+2 -2
View File
@@ -14,12 +14,12 @@ For integrating Paskia with your app frontend, see [integration](Integration.md)
### Public JSON API: /auth/api/*
| Method | Path | Used for | Responses |
| Method | Path | Used for | Expected responses |
|---:|---|---|---|
| GET | /auth/api/settings | Paskia configuration: RP info, base paths, session cookie name | 200 |
| GET | /auth/api/user-info | Full user profile: info, credentials, sessions, permissions | 200/401 |
| POST | /auth/api/logout | Terminate session and delete session cookie on the current host | 200 |
| POST | [/auth/api/validate](api/validate.md) | Validate and renew the session cookie; query [perm](api/perm.md), [max_age](api/max-age.md) | 200/401/403 |
| POST | [/auth/api/validate](api/validate.md) | Validate and renew the session cookie; query [perm](api/perm.md), [max_age](api/max-age.md), [renew](api/validate.md#query-parameters) | 200/401/403 |
| GET | [/auth/api/forward](api/forward.md) | Forward-auth with reverse proxies; see [proxy guides](proxy/index.md), query [perm](api/perm.md), [max_age](api/max-age.md) | 204/401/403 empty, json or html|
### User JSON API: /auth/api/user/*
docs/Integration.md
+1 -1
View File
@@ -122,7 +122,7 @@ This is useful for:
- Background jobs that need to verify a stored session
- Check extra permissions, get user context or renew session
Your backend can validate sessions directly by calling Paskia's validate endpoint [`/auth/api/validate`](api/validate.md). It generally expects client headers proxied as is, while on the URL you can specify exact requirements.
Your backend can validate sessions directly by calling Paskia's validate endpoint [`/auth/api/validate`](api/validate.md). It generally expects client headers proxied as is, while on the URL you can specify exact requirements. To verify a session without extending its lifetime or updating its IP / user-agent, pass `renew=0`.
Usually it is sufficient to simply forward the headers the client sent, assuming your proxy already preserved `Host` and set `X-Forwarded-For` (otherwise set them here with original host and IP). `User-Agent` should also be forwarded if available, omitted if not: do not let your backend HTTP client add its own header.
docs/api/validate.md
+2 -1
View File
@@ -12,6 +12,7 @@ See also the [API overview](../API.md) and the [integration guide](../Integratio
|-----------|-------------|
| perm | Required permissions. See the [perm argument](perm.md). |
| max_age | Require recent passkey use. See the [max_age argument](max-age.md). |
| renew | Pass `renew=0` to skip renewal: does no session updates, auth check only. |
## Request headers
@@ -19,7 +20,7 @@ See also the [API overview](../API.md) and the [integration guide](../Integratio
|---|---|---|
| Host | Forwarded directly from the client | Verifying the session's bound host |
| Cookie | Forwarded directly or just cookie `__Host-paskia` | Session ID |
| X-Forwarded-For | Real client IP | Recorded in session data instead of the backend/proxy IP; requires FORWARDED_ALLOW_IPS to trust the immediate peer |
| X-Forwarded-For | Real client IP | Recorded in logs and session data instead of the backend/proxy IP; requires FORWARDED_ALLOW_IPS to trust the immediate peer |
| User-Agent | Forward the original client UA if available; do not let your backend client add its own default | Recorded in session data only when the header is present; omitting it preserves the existing value |
See [integration documentation for backend validate requests](../Integration.md) for more detailed instructions, in particular for forwarding of client-provided headers.