paskia/API.md

Paskia API

Use these tables when integrating Paskia authentication into your app.

Web Interface

Method	Path	What it is for	Notes
GET	/auth/	User profile page
GET	/auth/admin/	Admin panel	Requires auth:admin (master) or org admin permissions.
GET	/auth/{token}	Reset / add credential URL (QR code link)	E.g. /auth/fun.cotton.fresh.xray.lava

Public JSON API: /auth/api/*

Method	Path	Used for	Notes
GET	/auth/api/settings	Paskia configuration	Returns RP info + base paths + session cookie name
POST	/auth/api/user-info	Full user profile	Basic information, credentials, sessions, permissions
POST	/auth/api/logout	Terminate session and delete session cookie	Signs out of the current site
POST	/auth/api/validate	Validate and renew session cookie	Optional query: perm= (repeatable)
GET	/auth/api/forward	Validate access (Caddy/Nginx)	204 on success; 401/403 otherwise (HTML if requested)

The forward endpoint takes query arguments perm= and max_age= for specific requirements on the validation of the current session.

User JSON API: /auth/api/user/*

Method	Path	Used for	Notes
PUT	/auth/api/user/display-name	Update the user’s display name	Body: JSON { "display_name": "..." }
POST	/auth/api/user/logout-all	Terminate all user sessions and clear cookie	Clears current cookie
DELETE	/auth/api/user/session/{session_id}	Terminate one session	Session IDs are server-issued
DELETE	/auth/api/user/credential/{uuid}	Delete a credential	Requires recent authentication
POST	/auth/api/user/create-link	Create a device-add link	Requires recent authentication

Admin API: /auth/api/admin/*

Normally only used via admin panel.

WebSockets: /auth/ws/*

Path	Used for	Notes
WS /auth/ws/authenticate	Passkey authentication	Returns a session_token
WS /auth/ws/register	Register a new credential	Optional query: reset=<token>, name=<display name>
WS /auth/ws/remote-auth/request	Start a cross-device login/registration request	Returns a pairing code
WS /auth/ws/remote-auth/permit	Approve/deny a pairing code	Used from an already-authenticated device

Auth host mode (--auth-host)

Path / type	What happens on non-auth hosts
/auth/api/*	Served normally
/auth/api/user/*	404
/auth/api/admin/*	404
/auth/ws/*	404

On the auth host itself some Web UI paths are made available at site root instead, but API stays in /auth/api and is fully accessible.