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/realms/	List realms (rp-ids) with derived URLs	200/401/403
POST	/auth/api/admin/realms/	Create realm {rp_id, rp_name?, auth_host?, origins?, related_origins?}	200/400/401/403
PATCH	/auth/api/admin/realms/{rp_id}	Update realm rp_name/auth_host/origins/related_origins	200/400/401/403
DELETE	/auth/api/admin/realms/{rp_id}	Delete realm (refused while credentials remain)	200/400/401/403

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

origins is an allow-list of sign-in sites within the realm's domain (empty = the rp-id and all subdomains may authenticate). related_origins lists other domains that may assert this realm's rp-id (WebAuthn Related Origin Requests, max 5); those are published at /.well-known/webauthn on the rp-id host. Entries filed under the wrong list are rejected: cross-domain entries in origins, in-domain entries in related_origins.

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 realm may configure a dedicated authentication host (auth-host, a subdomain of the rp-id), either at bootstrap (paskia init --auth-host) or via the Realms 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.

Shared auth host across realms

When one realm has an auth host, other realms without their own use it as their effective auth host: their WebSocket and cross-device flows are directed there, but their own /auth/ still serves the full profile (host mode is keyed off the realm's own auth host only). /auth/api/settings exposes both: auth_host (effective) and own_auth_host (this realm only, null when unset).

Related Origin Requests: /.well-known/webauthn

GET /.well-known/webauthn returns {"origins": [...]} listing the realm'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 realm's rp-id. Returns 404 when the realm has no related origins. If the rp-id's main site is hosted elsewhere, serve the JSON statically there (copy it from this instance).