Update documentation.

API.md

@@ -1,33 +1,28 @@
 # PassKey Auth API Documentation
 
-This document describes all API endpoints available in the PassKey Auth FastAPI application.
+This document describes all API endpoints available in the PassKey Auth FastAPI application, that by default listens on `localhost:4401` ("for authentication required").
-
-## Base URL
-- **Development**: `http://localhost:4401`
-- All endpoints are prefixed with `/auth/`
 
 ### HTTP Endpoints
-GET /auth/ - Main authentication app
-GET /auth/api/forward - Authentication validation for Caddy/Nginx (was /auth/forward-auth)
-		- On success returns `204 No Content` with the following headers:
-			- `Remote-User`: authenticated user UUID
-			- `Remote-Name`: display name
-			- `Remote-Groups`: comma-separated permission IDs (no spaces)
-			- `Remote-Org`: organization UUID
-			- `Remote-Org-Name`: organization display name
-			- `Remote-Role`: role UUID
-			- `Remote-Role-Name`: role display name
-			- `Remote-Session-Expires`: session expiry timestamp (ISO 8601)
-			- `Remote-Credential`: credential UUID backing the session
-POST /auth/validate - Token validation endpoint
-POST /auth/user-info - Get authenticated user information
-POST /auth/logout - Logout current user
-POST /auth/set-session - Set session cookie from Authorization header
-DELETE /auth/credential/{uuid} - Delete specific credential
-POST /auth/create-link - Create device addition link
-GET /auth/{reset_token} - Process reset token and redirect
 
-### WebSocket Endpoints
+GET /auth/ - Main authentication app
+GET /auth/admin/ - Admin app for managing organisations, users and permissions
+GET /auth/{reset_token} - Process password reset/share token
+POST /auth/api/user-info - Get authenticated user information
+POST /auth/api/logout - Logout and delete session
+POST /auth/api/set-session - Set session cookie from Authorization header
+POST /auth/api/create-link - Create device addition link
+DELETE /auth/api/credential/{uuid} - Delete specific credential
+POST /auth/api/validate - Session validation and renewal endpoint (fetch regularly)
+GET /auth/api/forward - Authentication validation for Caddy/Nginx
+		- On success returns `204 No Content` with [user info](Headers.md)
+		- Otherwise returns
+		   * `401 Unauthorized` - authentication required
+		   * `403 Forbidden` - missing required permissions
+		   * Serves the authentication app for a login or permission denied page
+		- Does not renew session!
+
+### WebAuthn/Passkey endpoints (WebSockets)
+
 WS /auth/ws/register - Register new user with passkey
 WS /auth/ws/add_credential - Add new credential for existing user
 WS /auth/ws/authenticate - Authenticate user with passkey

Caddy.md

@@ -7,7 +7,9 @@ What these snippets do
 - Use the forward-auth interface `/auth/api/forward` to verify the required credentials
 - Render a login page or a permission denied page if needed (without changing URL)
 
-### 1) Your site has no auth yet — protect the whole thing
+Your backend may not use authentication at all, or it can make use of the user information passed via `Remote-*` headers by the authentication system, see [Headers.md](Headers.md) for details.
+
+### 1) Protect the full site (auth/all)
 
 Use this when you want “login required everywhere” which is useful to protect some service that doesn't have any authentication of its own:
 
@@ -21,7 +23,9 @@ localhost {
 
 The auth/all protects the entire site with a simple directive. Put your normal setup inside the block. In this example we don't require any permissions, only that the user is logged in. Instead of `""` you may specify `perm=myapp:login` or other permissions.
 
-### 2) Different areas, different permissions
+It is possible to add your own `handle @matcher` blocks prior importing `auth/all` for endpoints that don't require authentication, e.g. to exclude `/favicon.ico`.
+
+### 2) Different areas, different permissions (auth/setup, auth/require)
 
 When you need a more fine-grained control, use the auth/setup and auth/require snippets:
 
@@ -58,21 +62,3 @@ Note: We use the `handle @name` approach rather than `handle_path` to prevent th
 By default, the auth service is contacted at localhost port 4401 ("for authentication required"). You can point Caddy to a different by setting the `AUTH_UPSTREAM` environment variable for Caddy.
 
 If unset, the snippets use `:4401` by default.
-
-## Headers your app receives
-
-When a request is allowed, the auth service adds these headers before proxying to your app (e.g., the service at `:3000`). Your app can use them for user context and authorization.
-
-| Header | Meaning | Example |
-|---|---|---|
-| `Remote-User` | Authenticated user UUID | `3f1a2b3c-4d5e-6789-abcd-ef0123456789` |
-| `Remote-Name` | User display name | `Jane Doe` |
-| `Remote-Org` | Organization UUID | `a1b2c3d4-1111-2222-3333-444455556666` |
-| `Remote-Org-Name` | Organization display name | `Acme Inc` |
-| `Remote-Role` | Role UUID | `b2c3d4e5-2222-3333-4444-555566667777` |
-| `Remote-Role-Name` | Role display name | `Administrators` |
-| `Remote-Groups` | Comma‑separated permissions the user has | `myapp:reports,auth:admin` |
-| `Remote-Session-Expires` | Session expiry timestamp (ISO 8601) | `2025-09-25T14:30:00Z` |
-| `Remote-Credential` | Credential UUID backing the session | `c3d4e5f6-3333-4444-5555-666677778888` |
-
-Note: Incoming `Remote-*` headers from clients are stripped by `auth/setup` or `auth/all`, so apps can trust these values.

Headers.md

@@ -0,0 +1,17 @@
+## Headers your app receives
+
+When a request is allowed, the auth service adds these headers before proxying to your app (e.g., the service at `:3000`). Your app can use them for user context and authorization.
+
+| Header | Meaning | Example |
+|---|---|---|
+| `Remote-User` | Authenticated user UUID | `3f1a2b3c-4d5e-6789-abcd-ef0123456789` |
+| `Remote-Name` | User display name | `Jane Doe` |
+| `Remote-Org` | Organization UUID | `a1b2c3d4-1111-2222-3333-444455556666` |
+| `Remote-Org-Name` | Organization display name | `Acme Inc` |
+| `Remote-Role` | Role UUID | `b2c3d4e5-2222-3333-4444-555566667777` |
+| `Remote-Role-Name` | Role display name | `Administrators` |
+| `Remote-Groups` | Comma‑separated permissions the user has | `myapp:reports,auth:admin` |
+| `Remote-Session-Expires` | Session expiry timestamp (ISO 8601) | `2025-09-25T14:30:00Z` |
+| `Remote-Credential` | Credential UUID backing the session | `c3d4e5f6-3333-4444-5555-666677778888` |
+
+Note: Any incoming `Remote-*` headers from clients are stripped by our [Caddy configuration](Caddy.md), so that apps can trust these values.