LeoVasanko/paskia
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Update API and proxy docs

Browse Source
This commit is contained in:
LeoVasanko
2026-08-10 21:35:46 +00:00
parent 6f5287e070
commit 00ef0ae2e7
15 changed files with 1107 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
+70 -71
View File
@@ -1,102 +1,101 @@
# 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 | Notes |
| Method | Path | What it is for | Responses |
|---:|---|---|---|
| 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` |
| 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/*`
### Public JSON API: /auth/api/*
| Method | Path | Used for | Notes |
| Method | Path | Used for | Responses |
|---:|---|---|---|
| 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) |
| 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) | 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|
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/*
### User JSON API: `/auth/api/user/*`
| Method | Path | Used for | Notes |
| Method | Path | Used for | Responses |
|---:|---|---|---|
| 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 |
| 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. 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.
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/*`
### 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.
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 |
| Method | Path | Used for | Responses |
|---:|---|---|---|
| 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 |
| 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/server-config/ | Get server config | 200/401/403 |
| PATCH | /auth/api/admin/server-config/ | Update server config | 200/401/403 |
Admins edit user avatars through the same canonical `/auth/api/user/{uuid}/profile.webp` PUT and DELETE endpoints.
### WebSockets: `/auth/ws/*`
### 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 |
| 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`)
### 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.
- 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
- `/auth/api/*` is served normally.
- `/auth/api/user/*`, `/auth/api/admin/*`, and `/auth/ws/*` don't exist.
- /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 auth host, and must have an allowed origin corresponding to the host where the user is logging in, that the session is tied with.