LeoVasanko
95c163e37a
- backend avatar storage and OIDC picture claims - profile and admin UI components - admin org cards, tests, and docs
103 lines
6.8 KiB
Markdown
103 lines
6.8 KiB
Markdown
# Paskia API
|
||
|
||
For integrating Paskia with your app frontend, see [integration](Integration.md).
|
||
|
||
## Web Interface
|
||
|
||
| Method | Path | What it is for | Notes |
|
||
|---:|---|---|---|
|
||
| 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` |
|
||
|
||
### Public JSON API: `/auth/api/*`
|
||
|
||
| Method | Path | Used for | Notes |
|
||
|---:|---|---|---|
|
||
| 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) |
|
||
|
||
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/*`
|
||
|
||
| Method | Path | Used for | Notes |
|
||
|---:|---|---|---|
|
||
| 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 |
|
||
|
||
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.
|
||
|
||
### 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 | Notes |
|
||
|---:|---|---|---|
|
||
| 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 |
|
||
|
||
Admins edit user avatars through the same canonical `/auth/api/user/{uuid}/profile.webp` PUT and DELETE endpoints.
|
||
|
||
### 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 (`--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.
|
||
|
||
#### 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.
|