Docs updates.
This commit is contained in:
Leo Vasanko
@@ -1,203 +1,58 @@
|
||||
# Paskia HTTP + WebSocket surface
|
||||
# Paskia endpoints (integration-focused)
|
||||
|
||||
This document is a factual map of the URLs Paskia exposes.
|
||||
Use these tables when integrating Paskia authentication into your app.
|
||||
|
||||
Two important distinctions:
|
||||
## Behavior when `--auth-host` is enabled
|
||||
|
||||
1. **User‑navigable endpoints**: URLs a human types/scans into a browser (address bar / QR).
|
||||
2. **API endpoints**: URLs the app uses programmatically (frontend or backend).
|
||||
| Path / type | What happens on non-auth hosts |
|
||||
|---|---|
|
||||
| `/auth/api/*` | Served normally |
|
||||
| `/auth/api/user/*` | `404` |
|
||||
| `/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) |
|
||||
|
||||
Within **API endpoints**, the most important group comes first:
|
||||
## Browser URLs (user-navigable)
|
||||
|
||||
- **`/auth/api/*`**: stable API surface that is reachable on any host (including non‑auth hosts).
|
||||
- **Auth‑host‑only namespaces**: only reachable on the dedicated auth host when `--auth-host` is configured.
|
||||
| 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 |
|
||||
|
||||
## Host modes (what changes when `--auth-host` is set)
|
||||
## App HTTP API (reachable on any host): `/auth/api/*`
|
||||
|
||||
Paskia can run in either mode:
|
||||
| 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 <session_token>`; 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=<token>`; invalid/expired returns `404` |
|
||||
| POST | `/auth/api/user-info` | Fetch user info for UI | Either session cookie, or `reset=<token>` for reset flows |
|
||||
|
||||
- **Multi‑host** (default, no `--auth-host`): all routes below are served on the current host.
|
||||
- **Dedicated auth host** (`--auth-host auth.example.com`):
|
||||
- Certain UI routes are redirected to the auth host.
|
||||
- Certain sensitive API and WebSocket namespaces are **not served** on non‑auth hosts (they return `404`).
|
||||
See [Headers.md](Headers.md) for the `Remote-*` header contract used by `/auth/api/forward`.
|
||||
|
||||
Rules are enforced by middleware in `paskia/fastapi/auth_host.py`.
|
||||
## Auth-host-only HTTP APIs (usually not needed for app integration)
|
||||
|
||||
### Summary table (dedicated auth host mode)
|
||||
| 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) |
|
||||
|
||||
| Category | Example path | On non‑auth hosts | On auth host |
|
||||
|---|---|---:|---:|
|
||||
| User‑navigable UI (root/admin/token) | `/admin/`, `/{token}` | 307 redirect (strip `/auth` when present) | served locally |
|
||||
| Static assets | `/auth/assets/*` | served locally | served locally |
|
||||
| App API (stable surface) | `/auth/api/validate` | served locally | served locally |
|
||||
| Auth‑host‑only API | `/auth/api/admin/*`, `/auth/api/user/*` | **404** | served locally |
|
||||
| Auth‑host‑only WebSockets | `/auth/ws/*` | **404** | served locally |
|
||||
## WebSockets (auth-host-only when `--auth-host` is enabled)
|
||||
|
||||
Notes:
|
||||
- “Strip `/auth`” applies only to UI redirects (e.g. `/auth/admin/` → `/admin/` on the auth host).
|
||||
- Redirects use HTTP `307` so method/body are preserved.
|
||||
|
||||
---
|
||||
|
||||
## API endpoints (programmatic)
|
||||
|
||||
### 1) Stable app API (reachable on any host): `/auth/api/*`
|
||||
|
||||
These endpoints are intended for programmatic use by:
|
||||
|
||||
- the browser frontend, and/or
|
||||
- backend services (reverse proxies, gateways) that need to validate sessions/permissions.
|
||||
|
||||
They remain under the `/auth/api/` prefix even when the auth UI moves to `/` on the auth host.
|
||||
|
||||
#### Session validation & permission checks
|
||||
|
||||
`POST /auth/api/validate`
|
||||
- Purpose: validate the current session cookie and optionally renew it (sliding expiry).
|
||||
- Query: `perm=<id>` (repeatable) — all listed permission IDs are required.
|
||||
- Response: JSON with `valid`, `user_uuid`, `renewed`.
|
||||
|
||||
`GET /auth/api/forward`
|
||||
- Purpose: “forward auth” endpoint for reverse proxies (Caddy/Nginx). Returns `204` with `Remote-*` headers on success.
|
||||
- Query:
|
||||
- `perm=<id>` (repeatable): required permissions.
|
||||
- `max_age=<duration>`: require recent authentication (e.g. `5m`, `1h`, `30s`).
|
||||
- Response:
|
||||
- success: `204 No Content` + headers
|
||||
- failure: `4xx` with either JSON or HTML depending on `Accept`.
|
||||
|
||||
See [Headers.md](Headers.md) for the `Remote-*` header contract.
|
||||
|
||||
#### Client configuration
|
||||
|
||||
`GET /auth/api/settings`
|
||||
- Purpose: fetch runtime configuration for the frontend (RP ID/name, base paths, auth-host mode).
|
||||
|
||||
#### Reset / link flows
|
||||
|
||||
`GET /auth/api/token-info?token=<token>`
|
||||
- Purpose: validate a reset token and return minimal metadata for the reset UI.
|
||||
- Notes: invalid or expired tokens return `404`.
|
||||
|
||||
`POST /auth/api/user-info`
|
||||
- Purpose: fetch user info.
|
||||
- Modes:
|
||||
- session mode: uses auth cookie
|
||||
- reset mode: pass `reset=<token>` (for reset/device-add flows)
|
||||
|
||||
#### Session cookie management
|
||||
|
||||
`POST /auth/api/logout`
|
||||
- Purpose: delete the current session (best-effort) and clear the auth cookie.
|
||||
|
||||
`POST /auth/api/set-session`
|
||||
- Purpose: exchange a Bearer session token for an auth cookie.
|
||||
- Auth: `Authorization: Bearer <session_token>`.
|
||||
|
||||
---
|
||||
|
||||
### 2) Auth‑host‑only API (not reachable on other hosts): `/auth/api/user/*`
|
||||
|
||||
These endpoints are still “app API”, but are intentionally blocked on non‑auth hosts when `--auth-host` is configured.
|
||||
|
||||
Base prefix: `/auth/api/user`
|
||||
|
||||
`PUT /auth/api/user/display-name`
|
||||
- Body: JSON `{ "display_name": "…" }`
|
||||
|
||||
`POST /auth/api/user/logout-all`
|
||||
- Purpose: terminate all sessions for the user; clears current cookie.
|
||||
|
||||
`DELETE /auth/api/user/session/{session_id}`
|
||||
- Purpose: terminate a specific session for the current user.
|
||||
|
||||
`DELETE /auth/api/user/credential/{uuid}`
|
||||
- Purpose: delete a credential (requires recent authentication).
|
||||
|
||||
`POST /auth/api/user/create-link`
|
||||
- Purpose: create a device addition link (reset token) for the current user (requires recent authentication).
|
||||
|
||||
---
|
||||
|
||||
### 3) Auth‑host‑only admin API (not reachable on other hosts): `/auth/api/admin/*`
|
||||
|
||||
Base prefix: `/auth/api/admin`
|
||||
|
||||
UI root (served by the admin sub-app):
|
||||
- `GET /auth/api/admin/` (serves the admin SPA HTML)
|
||||
|
||||
Organizations:
|
||||
- `GET /auth/api/admin/orgs`
|
||||
- `POST /auth/api/admin/orgs`
|
||||
- `PUT /auth/api/admin/orgs/{org_uuid}`
|
||||
- `DELETE /auth/api/admin/orgs/{org_uuid}`
|
||||
- `POST /auth/api/admin/orgs/{org_uuid}/permission`
|
||||
- `DELETE /auth/api/admin/orgs/{org_uuid}/permission`
|
||||
|
||||
Roles:
|
||||
- `POST /auth/api/admin/orgs/{org_uuid}/roles`
|
||||
- `PUT /auth/api/admin/orgs/{org_uuid}/roles/{role_uuid}`
|
||||
- `DELETE /auth/api/admin/orgs/{org_uuid}/roles/{role_uuid}`
|
||||
|
||||
Users:
|
||||
- `POST /auth/api/admin/orgs/{org_uuid}/users`
|
||||
- `PUT /auth/api/admin/orgs/{org_uuid}/users/{user_uuid}/role`
|
||||
- `POST /auth/api/admin/orgs/{org_uuid}/users/{user_uuid}/create-link`
|
||||
- `GET /auth/api/admin/orgs/{org_uuid}/users/{user_uuid}`
|
||||
- `PUT /auth/api/admin/orgs/{org_uuid}/users/{user_uuid}/display-name`
|
||||
- `DELETE /auth/api/admin/orgs/{org_uuid}/users/{user_uuid}/credentials/{credential_uuid}`
|
||||
- `DELETE /auth/api/admin/orgs/{org_uuid}/users/{user_uuid}/sessions/{session_id}`
|
||||
|
||||
Permissions (global):
|
||||
- `GET /auth/api/admin/permissions`
|
||||
- `POST /auth/api/admin/permissions`
|
||||
- `PUT /auth/api/admin/permission`
|
||||
- `POST /auth/api/admin/permission/rename`
|
||||
- `DELETE /auth/api/admin/permission`
|
||||
|
||||
---
|
||||
|
||||
## WebSocket endpoints
|
||||
|
||||
All WebSocket endpoints are mounted under `/auth/ws/` and are **auth‑host‑only** when `--auth-host` is configured.
|
||||
|
||||
### Passkey WebAuthn
|
||||
|
||||
`WS /auth/ws/authenticate`
|
||||
- Purpose: authenticate using a passkey.
|
||||
- Response includes `session_token` (use `POST /auth/api/set-session` to set the cookie).
|
||||
|
||||
`WS /auth/ws/register`
|
||||
- Purpose: register a new credential.
|
||||
- Query:
|
||||
- `reset=<token>` (optional): allow registration via reset link
|
||||
- `name=<display name>` (optional)
|
||||
|
||||
### Remote authentication (cross-device)
|
||||
|
||||
Mounted under `/auth/ws/remote-auth`:
|
||||
|
||||
`WS /auth/ws/remote-auth/request`
|
||||
- Purpose: create a pairing code and wait for approval.
|
||||
|
||||
`WS /auth/ws/remote-auth/permit`
|
||||
- Purpose: approve/deny a pairing code from another device.
|
||||
|
||||
---
|
||||
|
||||
## User‑navigable endpoints (browser)
|
||||
|
||||
These are the URLs a user should be able to open directly.
|
||||
|
||||
`GET /` and `GET /auth/`
|
||||
- Serves the user profile app.
|
||||
|
||||
`GET /admin/` (and legacy `/auth/admin/`)
|
||||
- Admin UI (may redirect to the auth host in dedicated auth-host mode).
|
||||
|
||||
`GET /{token}` (and legacy `/auth/{token}`)
|
||||
- Reset / device addition UI for a single path segment token.
|
||||
- Token format is validated; malformed tokens return `404`.
|
||||
|
||||
`GET /auth/restricted/`
|
||||
- Special HTML UI used for iframe-based authentication flows (primarily via `/auth/api/forward`).
|
||||
| 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=<token>`, `name=<display 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 |
|
||||
|
||||
Reference in New Issue
Block a user