From e5b84dd28c68903ad559b3e414e1de248c660b85 Mon Sep 17 00:00:00 2001 From: Leo Vasanko Date: Fri, 19 Dec 2025 17:34:09 +0000 Subject: [PATCH] Docs updates. --- API.md | 99 ++++++++++++++++++++++++++++++---------------------------- 1 file changed, 52 insertions(+), 47 deletions(-) diff --git a/API.md b/API.md index a5acb24..76f7051 100644 --- a/API.md +++ b/API.md @@ -1,8 +1,58 @@ -# Paskia endpoints (integration-focused) +# Paskia API Use these tables when integrating Paskia authentication into your app. -## Behavior when `--auth-host` is enabled +### Browser URLs (user-navigable) + +| Method | Path | What it is for | Notes | +|---:|---|---|---| +| GET | `/` | User profile UI | On app hosts you can also use `/auth/` | +| GET | `/auth/` | User profile UI (legacy entry) | Alternative entry point for `/` | +| GET | `/admin/` | Admin UI | Legacy entry: `/auth/admin/` | +| GET | `/{token}` | Reset / registration / device-add UI | Legacy entry: `/auth/{token}`; invalid tokens return `404` | +| GET | `/auth/restricted/` | HTML UI used by the auth-forward flow | Typically shown via `/auth/api/forward` on failures | + +### App HTTP API: `/auth/api/*` + +| Method | Path | Used for | Inputs / outputs (high level) | +|---:|---|---|---| +| POST | `/auth/api/validate` | Validate session cookie; optionally renew | Query: `perm` (repeatable). JSON response includes `valid`, `user_uuid`, `renewed` | +| GET | `/auth/api/forward` | Reverse-proxy auth check (Caddy/Nginx) | Query: `perm` (repeatable), `max_age`. Success: `204` with `Remote-*` headers; failures: `4xx` JSON or HTML depending on `Accept` | +| POST | `/auth/api/set-session` | Turn a Bearer session token into a cookie | Header: `Authorization: Bearer `; sets cookie | +| POST | `/auth/api/logout` | Clear cookie and delete session (best-effort) | Returns JSON message | +| GET | `/auth/api/settings` | Fetch runtime settings for clients | Returns RP info + base paths + session cookie name | +| GET | `/auth/api/token-info` | Validate reset token and fetch minimal metadata | Query: `token=`; invalid/expired returns `404` | +| POST | `/auth/api/user-info` | Fetch user info for UI | Either session cookie, or `reset=` for reset flows | + +See [Headers.md](Headers.md) for the `Remote-*` header contract used by `/auth/api/forward`. + +### User account HTTP API: `/auth/api/user/*` + +| Method | Path | Used for | Notes | +|---:|---|---|---| +| PUT | `/auth/api/user/display-name` | Update the user’s display name | Body: JSON `{ "display_name": "..." }` | +| POST | `/auth/api/user/logout-all` | Terminate all user sessions and clear cookie | Clears current 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 | + +### Admin HTTP API: `/auth/api/admin/*` + +| Method | Path | Used for | Notes | +|---:|---|---|---| +| GET | `/auth/api/admin/` | Admin UI entry | Serves the admin SPA HTML | +| * | `/auth/api/admin/*` | Admin management API | Organizations, roles, users, permissions | + +### WebSockets: `/auth/ws/*` + +| Path | Used for | Notes | +|---|---|---| +| `WS /auth/ws/authenticate` | Passkey authentication | Returns a `session_token` that can be exchanged via `POST /auth/api/set-session` | +| `WS /auth/ws/register` | Register a new credential | Optional query: `reset=`, `name=` | +| `WS /auth/ws/remote-auth/request` | Start a cross-device login/registration request | Returns a pairing code | +| `WS /auth/ws/remote-auth/permit` | Approve/deny a pairing code | Used from an already-authenticated device | + +### Auth host mode (`--auth-host`) | Path / type | What happens on non-auth hosts | |---|---| @@ -11,48 +61,3 @@ Use these tables when integrating Paskia authentication into your app. | `/auth/api/admin/*` | `404` | | `/auth/ws/*` | `404` | | Browser UI URLs like `/admin/`, `/{token}`, and legacy `/auth/...` | `307` redirect to the auth host (UI redirects strip the `/auth` prefix) | - -## Browser URLs (user-navigable) - -| Method | Path | What it is for | Notes | -|---:|---|---|---| -| GET | `/` | User profile UI | On app hosts you can also use `/auth/` | -| GET | `/auth/` | User profile UI (legacy entry) | Redirects to `/` on the auth host | -| GET | `/admin/` | Admin UI | Legacy entry: `/auth/admin/` | -| GET | `/{token}` | Reset / registration / device-add UI | Legacy entry: `/auth/{token}`; invalid tokens return `404` | -| GET | `/auth/restricted/` | HTML UI used by the auth-forward flow | Typically shown via `/auth/api/forward` on failures | - -## App HTTP API (reachable on any host): `/auth/api/*` - -| Method | Path | Used for | Inputs / outputs (high level) | -|---:|---|---|---| -| POST | `/auth/api/validate` | Validate session cookie; optionally renew | Query: `perm` (repeatable). JSON response includes `valid`, `user_uuid`, `renewed` | -| GET | `/auth/api/forward` | Reverse-proxy auth check (Caddy/Nginx) | Query: `perm` (repeatable), `max_age`. Success: `204` with `Remote-*` headers; failures: `4xx` JSON or HTML depending on `Accept` | -| POST | `/auth/api/set-session` | Turn a Bearer session token into a cookie | Header: `Authorization: Bearer `; sets cookie | -| POST | `/auth/api/logout` | Clear cookie and delete session (best-effort) | Returns JSON message | -| GET | `/auth/api/settings` | Fetch runtime settings for clients | Returns RP info + base paths + auth-host info | -| GET | `/auth/api/token-info` | Validate reset token and fetch minimal metadata | Query: `token=`; invalid/expired returns `404` | -| POST | `/auth/api/user-info` | Fetch user info for UI | Either session cookie, or `reset=` for reset flows | - -See [Headers.md](Headers.md) for the `Remote-*` header contract used by `/auth/api/forward`. - -## Auth-host-only HTTP APIs (usually not needed for app integration) - -| Audience | Method | Path | Used for | -|---:|---:|---|---| -| User | PUT | `/auth/api/user/display-name` | Update the user’s display name | -| User | POST | `/auth/api/user/logout-all` | Terminate all user sessions and clear cookie | -| User | DELETE | `/auth/api/user/session/{session_id}` | Terminate one session | -| User | DELETE | `/auth/api/user/credential/{uuid}` | Delete a credential (requires recent auth) | -| User | POST | `/auth/api/user/create-link` | Create a device-add link (requires recent auth) | -| Admin | GET | `/auth/api/admin/` | Admin UI entry (serves the admin SPA HTML) | -| Admin | * | `/auth/api/admin/*` | Admin management API (orgs, roles, users, permissions) | - -## WebSockets (auth-host-only when `--auth-host` is enabled) - -| Path | Used for | Notes | -|---|---|---| -| `WS /auth/ws/authenticate` | Passkey authentication | Returns a `session_token` that can be exchanged via `POST /auth/api/set-session` | -| `WS /auth/ws/register` | Register a new credential | Optional query: `reset=`, `name=` | -| `WS /auth/ws/remote-auth/request` | Start a cross-device login/registration request | Returns a pairing code | -| `WS /auth/ws/remote-auth/permit` | Approve/deny a pairing code | Used from an already-authenticated device |