API Documentation

25 routes · Version fe45baa

Pages

GET /

Serves the main HTML page.

Response: text/html
GET /api/docs

This page. Auto-generated API documentation.

Response: text/html
GET /qr

QR code scanner page.

Response: text/html
GET /login

Login page with username/password and passkey support.

Response: text/html
GET /logout

Clear session cookie and redirect to home.

Response: 302 Redirect
GET /settings Auth

Settings page for passkey management. Requires authentication.

Response: text/html
GET /admin/settings Auth Admin

Admin settings page with site-wide toggles. Requires admin authentication.

Response: text/html

Authentication

POST /api/v1/auth/login

Authenticate with username and password. Returns a temporary bearer token.

Request: {"username": "string", "password": "string"}
Response: {"token": "string", "expiresAt": 1750000000000}
Errors:
  • 400 Invalid request body
  • 401 Invalid credentials
POST /api/v1/auth/logout

Revoke the bearer token from the Authorization header.

Response: {"message": "Logged out"}

WebAuthn

POST /api/v1/auth/webauthn/register/options Auth

Get WebAuthn registration options for the authenticated user.

Response: PublicKeyCredentialCreationOptions JSON
POST /api/v1/auth/webauthn/register Auth

Complete WebAuthn registration with attestation response.

Request: { id, rawId, type, attestationObject, clientDataJSON, name? }
Response: {"message": "Passkey registered"}
Errors:
  • 400 Invalid request body
  • 400 Invalid or expired challenge
POST /api/v1/auth/webauthn/login/options

Get WebAuthn login options with allowed credentials.

Response: PublicKeyCredentialRequestOptions JSON
POST /api/v1/auth/webauthn/login

Complete WebAuthn login with assertion response. Sets session cookie.

Request: { id, rawId, type, authenticatorData, clientDataJSON, signature, userHandle? }
Response: {"message": "Authenticated as <username>"}
Errors:
  • 400 Invalid request body
  • 400 Invalid or expired challenge
  • 401 Unknown credential
  • 401 Authentication failed
GET /api/v1/auth/webauthn/credentials Auth

List the authenticated user's registered passkeys.

Response: {"credentials": [{"id": "...", "name": "...", "createdAt": "..."}]}
DELETE /api/v1/auth/webauthn/credentials/{id} Auth

Delete a passkey owned by the authenticated user.

Response: {"message": "Credential deleted"}
Errors:
  • 400 Credential ID required
  • 404 Credential not found

QR Scanner

POST /api/v1/qr/scan

Upload a QR code image for processing. Multipart form data with field 'image'.

Request: multipart/form-data (field: image)
Response: {"content": "decoded QR string"}
Errors:
  • 400 No image provided
  • 400 File is not an image
  • 400 Image too large (max 10 MB)
  • 400 Could not decode QR code
  • 429 Rate limit exceeded (max 3 per 90 minutes)
  • 500 Processing failed

VGTU

GET /api/v1/vgtu/totp Auth

Returns the encrypted TOTP secret.

Response: text/plain (encrypted string)

Admin

POST /api/v1/admin/users Auth Admin

Register a new user.

Request: {"username": "string", "password": "string"}
Response: {"message": "User '<name>' created"}
Errors:
  • 400 Invalid request body
  • 400 Username and password must not be blank
  • 403 Admin access required
  • 409 User already exists
  • 409 Cannot register the admin user
GET /api/v1/admin/users Auth Admin

List all registered usernames.

Response: {"users": ["string"]}
Errors:
  • 403 Admin access required
DELETE /api/v1/admin/users/{username} Auth Admin

Delete a registered user by username.

Response: {"message": "User '<name>' deleted"}
Errors:
  • 400 Username is required
  • 403 Admin access required
  • 404 User not found
DELETE /api/v1/admin/qr-ratelimits Auth Admin

Clear all QR scan rate limit buckets.

Response: {"message": "QR rate limits cleared"}
Errors:
  • 403 Admin access required
GET /api/v1/admin/settings/qr-protection Auth Admin

Get the current QR protection state.

Response: {"enabled": true}
Errors:
  • 403 Admin access required
PUT /api/v1/admin/settings/qr-protection Auth Admin

Toggle QR protection. When enabled, QR scanner page and API require authentication.

Request: {"enabled": true}
Response: {"enabled": true}
Errors:
  • 400 Invalid request body
  • 403 Admin access required
GET /api/v1/admin/settings Auth Admin

Get all admin settings including QR protection state, env overrides, and env defaults.

Response: {"qrProtectionEnabled": true, "envOverrides": {"KEY": "value"}, "envDefaults": {"KEY": "value"}}
Errors:
  • 403 Admin access required
PUT /api/v1/admin/settings Auth Admin

Update all admin settings. Validates env values (not blank, URL format, boolean). Overrides take precedence over .env file values.

Request: {"qrProtectionEnabled": true, "envOverrides": {"KEY": "value"}}
Response: {"qrProtectionEnabled": true, "envOverrides": {"KEY": "value"}, "envDefaults": {"KEY": "value"}}
Errors:
  • 400 Invalid request body
  • 400 Validation error (key-specific)
  • 403 Admin access required