Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AZhur771/pivpn-web/llms.txt

Use this file to discover all available pages before exploring further.

PiVPN Web uses server-side sessions backed by a TypeORM session store. A session cookie (connect.sid) is set on successful login and must be present for all authenticated requests. Session cookies are HttpOnly, SameSite: strict, and optionally Secure when the IS_SECURE environment variable is set.

​
GET /api/session

Returns the authentication status of the current session. This endpoint is always accessible — no active session is required. It is useful for bootstrapping a UI to determine whether to show the login form. Response — authenticated 
{
  "authenticated": true,
  "username": "pi",
  "hostname": "raspberrypi",
  "isAdmin": true
}
Response — not authenticated 
{ "authenticated": false }
​
authenticated
boolean
required
true when a valid session exists for the current request, false otherwise.
​
username
string
The SSH user that PiVPN Web uses to connect to the host (the value of the SSH_USER environment variable). Only present when authenticated is true.
​
hostname
string
The hostname of the PiVPN host as returned by the hostname shell command. Only present when authenticated is true.
​
isAdmin
boolean
true when the logged-in user has the admin flag set in the database. Only present when authenticated is true.
Example 
curl http://localhost:3001/api/session

​
POST /api/session

Authenticates a user and creates a new session. Credentials are validated against the user database using bcrypt. On success the server responds with 204 No Content and sets a Set-Cookie header containing the session cookie. Store that cookie and send it with every subsequent request. No prior authentication is required to call this endpoint.
​
username
string
required
The username of the account to log in with. Corresponds to the login column in the user table.
​
password
string
required
The plain-text password. It is compared against the bcrypt hash stored in the database.
Request example 
{ "username": "admin", "password": "yourpassword" }
Response 204 No Content — session created. The Set-Cookie header contains the connect.sid session cookie. Error responses
StatusBodyWhen
500{ "error": "Missing username" }username field absent or empty
500{ "error": "Missing password" }password field absent or empty
500{ "error": "Wrong username or password" }User not found or password mismatch
The same "Wrong username or password" message is returned for both an unknown username and a wrong password. This is intentional — it prevents user enumeration.
curl example 
curl -c cookies.txt \
  -X POST http://localhost:3001/api/session \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "yourpassword"}'
The -c cookies.txt flag saves the session cookie to a file. Pass -b cookies.txt on subsequent requests to authenticate them.

​
DELETE /api/session

Logs out the current user and destroys the active session. Requires a valid session — unauthenticated requests are rejected with 401. After a successful logout the session store entry is removed and the cookie becomes invalid. Response 204 No Content Error responses
StatusBodyWhen
401{ "error": "Invalid Session: <id>" }No valid session is attached to the request
curl example 
curl -b cookies.txt \
  -X DELETE http://localhost:3001/api/session

Build docs developers (and LLMs) love

Get started for freeTalk to us