LeoVasanko/passkey-auth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation.

Browse Source
This commit is contained in:
Leo Vasanko
2025-09-26 16:59:18 -06:00
parent 8409c7726c
commit f065a8294f
3 changed files with 43 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
API.md
View File

@@ -1,33 +1,28 @@
# PassKey Auth API Documentation
This document describes all API endpoints available in the PassKey Auth FastAPI application.
## Base URL
- **Development**: `http://localhost:4401`
- All endpoints are prefixed with `/auth/`
This document describes all API endpoints available in the PassKey Auth FastAPI application, that by default listens on `localhost:4401` ("for authentication required").
### 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

26
CADDY.md → Caddy.md
View File

@@ -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.

17
Headers.md Normal file
View File

@@ -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.