paskia/docs/API.md

# 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/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?}` | 200/400/401/403 |
| PATCH | /auth/api/admin/realms/{rp_id} | Update realm rp_name/auth_host/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.

### 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).