paskia/docs/API.md

Paskia API

For integrating Paskia with your app frontend, see integration.

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
GET	/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), max_age=
GET	/auth/api/forward	Validate access (Caddy/Nginx)	204 on success; 401/403 otherwise (HTML if requested)

The validate and forward endpoints take 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
PATCH	/auth/api/user/display-name	Update the user’s display name	Body: JSON { "display_name": "..." }
GET	/auth/api/user/{uuid}/profile.webp	Canonical avatar image URL	Public on the auth host; serves image/webp with ETag and short-lived cache headers
PUT	/auth/api/user/{uuid}/profile.webp	Upload or replace a user avatar	Multipart form with file; upload must already be square WebP prepared in the browser
DELETE	/auth/api/user/{uuid}/profile.webp	Remove a user avatar	Allowed for the user, master admin, or org admin for users in the same org
POST	/auth/api/user/logout-all	Terminate all user sessions	Clears current host 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

These are used mostly from the user profile panel. The avatar route is also used by admins when managing other users. GET /auth/api/user-info includes user.avatar_url when the user has an uploaded avatar, using the same canonical /auth/api/user/{uuid}/profile.webp path.

Admin API: /auth/api/admin/*

Normally only used via admin panel, requires auth admin permissions and can modify any users, orgs and permissions the session has access to.

E.g. Org admin cannot see anything of the other orgs that he has no admin access to. Master admin auth:admin can see everything and create and manage orgs.

Method	Path	Used for	Notes
GET	/auth/api/admin/info	Admin overview	Returns orgs, permissions, OIDC clients info
POST	/auth/api/admin/permissions/	Create permission	Body: JSON with scope, display_name, domain
PATCH	/auth/api/admin/permissions/{uuid}	Update permission	Query params: display_name, scope, domain
DELETE	/auth/api/admin/permissions/{uuid}	Delete permission
POST	/auth/api/admin/orgs/	Create organization	Body: JSON with display_name, permissions
GET	/auth/api/admin/orgs/{uuid}	Get organization details
PATCH	/auth/api/admin/orgs/{uuid}	Update organization	Body: JSON with display_name
DELETE	/auth/api/admin/orgs/{uuid}	Delete organization
POST	/auth/api/admin/orgs/{uuid}/users	Create user in org	Body: JSON with display_name, role_uuid
POST	/auth/api/admin/orgs/{uuid}/roles	Create role in org	Body: JSON with display_name, permissions
POST	/auth/api/admin/orgs/{uuid}/permission	Grant permission to org	Query param: permission_uuid
DELETE	/auth/api/admin/orgs/{uuid}/permission	Revoke permission from org	Query param: permission_uuid
PATCH	/auth/api/admin/roles/{uuid}	Update role	Body: JSON with display_name
POST	/auth/api/admin/roles/{uuid}/permissions/{uuid}	Add permission to role
DELETE	/auth/api/admin/roles/{uuid}/permissions/{uuid}	Remove permission from role
DELETE	/auth/api/admin/roles/{uuid}	Delete role
PATCH	/auth/api/admin/users/{uuid}/role	Update user role	Body: JSON with role_uuid
PATCH	/auth/api/admin/users/{uuid}/info	Update user info	Body: JSON with display_name
GET	/auth/api/admin/users/{uuid}	Get user details
DELETE	/auth/api/admin/users/{uuid}	Delete user
POST	/auth/api/admin/users/{uuid}/create-link	Create device add link
DELETE	/auth/api/admin/users/{uuid}/credentials/{uuid}	Delete user credential
DELETE	/auth/api/admin/users/{uuid}/sessions/{key}	Delete user session
POST	/auth/api/admin/oidc-clients/	Create OIDC client	Body: JSON with client_name, redirect_uris
PATCH	/auth/api/admin/oidc-clients/{uuid}	Update OIDC client	Body: JSON with client_name, redirect_uris
PATCH	/auth/api/admin/oidc-clients/{uuid}/reset-secret	Reset client secret
DELETE	/auth/api/admin/oidc-clients/{uuid}	Delete OIDC client
GET	/auth/api/admin/server-config/	Get server config	Returns rp_name, auth_host, origins
PATCH	/auth/api/admin/server-config/	Update server config	Body: JSON with rp_name, auth_host, origins

Admins edit user avatars through the same canonical /auth/api/user/{uuid}/profile.webp PUT and DELETE endpoints.

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	Adding another passkey to current user or via reset token
WS /auth/ws/remote-auth/request	Start a cross-device login/registration request	Used from unauthenticated client
WS /auth/ws/remote-auth/permit	Approve/deny a pairing code	Used to accept the request, if same words are entered

These are for internal use only, but are documented here because they are the core piece in all passkey operations.

Auth host mode (--auth-host)

On the auth host:

• The Web UI is served at site root (e.g. admin UI at /admin/), and the /auth/... equivalents (e.g. /auth/admin/) redirect to the root paths.
• All of the API stays under /auth/api/*
• Auth WebSockets remain at /auth/ws/* but take connections from other hosts to issue sessions for each of those.

On non-auth hosts:

• /auth/ shows only minimal profile and allows logging out of the current site
• /auth/api/* is served normally.
• /auth/api/user/*, /auth/api/admin/*, and /auth/ws/* don't exist.