# Paskia API

[Integration](Integration.md) · [Proxy guides](proxy/index.md)

For integrating Paskia with your app frontend, see [integration](Integration.md).

## 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](api/validate.md) | Validate and renew the session cookie; query [perm](api/perm.md), [max_age](api/max-age.md), [renew](api/validate.md#query-parameters) | 200/401/403 |
| GET | [/auth/api/forward](api/forward.md) | Forward-auth with reverse proxies; see [proxy guides](proxy/index.md), query [perm](api/perm.md), [max_age](api/max-age.md) | 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).