vpn/docs/backend.md

Backend contract

The admin UI is a single backend/admin.html file. It sends the configured admin Bearer token in memory/session storage and calls only /admin/api/* endpoints.

Device flow

1. Operator creates a user and device in the page.
2. Backend returns a one-time enrollment_url and a stable subscription_url.
3. The app makes the first request with X-Device-Token: <random token> and User-Agent: vpnapp/vMAJOR.MINOR/DEVICE_UUID.
4. Backend checks URL UUID, credential, and User-Agent UUID atomically, records the User-Agent, and returns the user's decrypted-for-transport config payload.
5. Polling every few hours uses the same device token and bound User-Agent. A different installation cannot reuse the same device binding unless the token is copied; UUID and User-Agent alone never authenticate.

The device endpoint must be deployed behind TLS. The admin token is not accepted on /d/{device_id}. Server configs and user secrets are Fernet-encrypted at rest with VPNAPP_SECRET_KEY; only sanitized fields are shown in the admin list.

The reusable client-side request code is in app/services/subscription.py. It accepts an injected secret store, emits the required User-Agent, performs one-time enrollment, refreshes the device subscription asynchronously, and maps the response into the separate VLESS/Amnezia/FreeTurn profile models. Android should connect its injected store to Keystore-backed native storage before shipping credentials.