paskia/docs/API.md

Paskia API

Integration · Proxy guides

For integrating Paskia with your app frontend, see integration.

Web Interface

Method	Path	What it is for	Responses
GET	/auth/	User profile page	HTML 200/401
GET	/auth/admin/	Admin panel, requires auth:admin or org admin permissions	HTML 200/401/403
GET	/auth/{token}	Reset / add credential URL (QR code link), e.g. /auth/fun.cotton.fresh.xray.lava	HTML 200

Public JSON API: /auth/api/*

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	Validate and renew the session cookie; query perm, max_age, renew	200/401/403
GET	/auth/api/forward	Forward-auth with reverse proxies; see proxy guides, query perm, max_age	204/401/403 empty, json or html

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

Method	Path	Used for	Responses
PATCH	/auth/api/user/display-name	Update the user's display name	200/401
POST	/auth/api/user/logout-all	Terminate all user sessions	200/401
DELETE	/auth/api/user/session/{session_id}	Terminate one session	200/401
DELETE	/auth/api/user/credential/{uuid}	Delete a credential; requires recent authentication	200/401/403
POST	/auth/api/user/create-link	Create a device-add link; requires recent authentication	200/401/403
GET	/auth/api/user/{uuid}/profile.webp	Canonical avatar image URL, public on the auth host	200/304/404
PUT	/auth/api/user/{uuid}/profile.webp	Upload or replace an avatar; square WebP prepared in the browser	200/401/403
DELETE	/auth/api/user/{uuid}/profile.webp	Remove an avatar; allowed for the user or an admin	200/401/403

These are used mostly from the user profile panel by the user himself, but the profile pictures are public for all to read.

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	Responses
GET	/auth/api/admin/info	Admin overview: orgs, permissions, OIDC clients	200/401/403
POST	/auth/api/admin/permissions/	Create permission	200/401/403
PATCH	/auth/api/admin/permissions/{uuid}	Update permission	200/401/403
DELETE	/auth/api/admin/permissions/{uuid}	Delete permission	200/401/403
POST	/auth/api/admin/orgs/	Create organization	200/401/403
GET	/auth/api/admin/orgs/{uuid}	Get organization details	200/401/403
PATCH	/auth/api/admin/orgs/{uuid}	Update organization	200/401/403
DELETE	/auth/api/admin/orgs/{uuid}	Delete organization	200/401/403
POST	/auth/api/admin/orgs/{uuid}/users	Create user in org	200/401/403
POST	/auth/api/admin/orgs/{uuid}/roles	Create role in org	200/401/403
POST	/auth/api/admin/orgs/{uuid}/permission	Grant permission to org	200/401/403
DELETE	/auth/api/admin/orgs/{uuid}/permission	Revoke permission from org	200/401/403
PATCH	/auth/api/admin/roles/{uuid}	Update role	200/401/403
POST	/auth/api/admin/roles/{uuid}/permissions/{uuid}	Add permission to role	200/401/403
DELETE	/auth/api/admin/roles/{uuid}/permissions/{uuid}	Remove permission from role	200/401/403
DELETE	/auth/api/admin/roles/{uuid}	Delete role	200/401/403
PATCH	/auth/api/admin/users/{uuid}/role	Update user role	200/401/403
PATCH	/auth/api/admin/users/{uuid}/info	Update user info	200/401/403
GET	/auth/api/admin/users/{uuid}	Get user details	200/401/403
DELETE	/auth/api/admin/users/{uuid}	Delete user	200/401/403
POST	/auth/api/admin/users/{uuid}/create-link	Create device add link	200/401/403
DELETE	/auth/api/admin/users/{uuid}/credentials/{uuid}	Delete user credential	200/401/403
DELETE	/auth/api/admin/users/{uuid}/sessions/{key}	Delete user session	200/401/403
POST	/auth/api/admin/oidc-clients/	Create OIDC client	200/401/403
PATCH	/auth/api/admin/oidc-clients/{uuid}	Update OIDC client	200/401/403
PATCH	/auth/api/admin/oidc-clients/{uuid}/reset-secret	Reset client secret	200/401/403
DELETE	/auth/api/admin/oidc-clients/{uuid}	Delete OIDC client	200/401/403
GET	/auth/api/admin/domains/	List domains (rp-ids) with derived URLs	200/401/403
POST	/auth/api/admin/domains/	Create domain {rp_id, rp_name?, origins?, related?}	200/400/401/403
PATCH	/auth/api/admin/domains/{rp_id}	Update domain rp_name/origins/related	200/400/401/403
DELETE	/auth/api/admin/domains/{rp_id}	Delete domain (refused while credentials remain)	200/400/401/403

Domain endpoints require the auth:admin permission; writes additionally require recent authentication (5 minutes). Changes are validated cross-domain and apply immediately.

origins is a single object keyed by all of the domain's sign-in sites. Entries within the rp-id domain are in-domain sites: bare hosts, *. wildcards under the rp-id (matching the base domain and subdomains over https only — any scheme and port under localhost), or full origins when not https; the plain * wildcard is not accepted. Entries outside the rp-id domain are related origins that may assert this domain's rp-id (WebAuthn Related Origin Requests, max 5, no wildcards); those are published at /.well-known/webauthn on the rp-id host. An empty object allows nothing of the domain itself. A value of true marks presence; {"auth_host": true} additionally marks an in-domain entry as the domain's authentication host.

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 (dedicated auth site)

A domain may configure a dedicated authentication host (auth-host, a subdomain of the rp-id) via the Domains admin panel.

On the auth host:

• The Web UI is served at site root instead of /auth/* (that redirects to 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, link to full profile on auth host
• /auth/api/* is served normally.
• /auth/api/user/, /auth/api/admin/, and /auth/ws/* don't exist.

The WebSocket connections are directed to the auth host, and must have an allowed origin corresponding to the host where the user is logging in, that the session is tied with.

Auth hosts and other domains

Auth hosts are strictly per-domain: a domain without its own auth host uses its own hosts for the WebSocket flows, and /auth/api/settings reports auth_host (and the identical own_auth_host) as null. One domain's auth host never serves another domain implicitly. To consolidate logins on one host, mark that host as the auth host on each domain that should use it (possible when the host lies under each domain's rp-id, i.e. nested rp-ids); dispatch resolves a shared host to the best-matching (longest rp-id suffix) domain.

Related Origin Requests: /.well-known/webauthn

GET /.well-known/webauthn returns {"origins": [...]} listing the domain's related origins (configured origins on domains unrelated to the rp-id), per WebAuthn Related Origin Requests. Browsers fetch this from the rp-id domain when an unrelated origin runs a ceremony with this domain's rp-id. Returns 404 when the domain has no related origins. If the rp-id's main site is hosted elsewhere, serve the JSON statically there (copy it from this instance).