docs/core.md

Core

REST API server — the control plane of Nexuma. Manages users, tariffs, subscriptions, nodes, traffic accounting, and generates subscription configs for VPN clients.

Configuration

Edit the environment variables in docker-compose.base.yml:

Variable	Required	Description
DB_HOST	Yes	PostgreSQL host
DB_PORT	Yes	PostgreSQL port
DB_USER	Yes	Database user
DB_PASSWORD	Yes	Database password
DB_NAME	Yes	Database name
REDIS_HOST	Yes	Redis host
REDIS_PORT	Yes	Redis port
JWT_SECRET	Yes	Access token secret
JWT_REFRESH_SECRET	Yes	Refresh token secret
JWT_EXPIRES_IN	No	Access token TTL (default: 15m)
JWT_REFRESH_EXPIRES_IN	No	Refresh token TTL (default: 7d)
TELEGRAM_BOT_TOKEN	No	Enables Telegram bot and OAuth login
CORS_ORIGINS	No	Allowed CORS origins (default: *)

API Overview

Public

• POST /auth/register — create account
• POST /auth/login — login, get JWT tokens
• POST /auth/refresh — refresh access token
• GET /sub/:uuid — subscription config for VPN clients (base64 URI list)
• GET /sub/:uuid/info — subscription info (JSON)
• GET /health, GET /metrics

User

• GET /me — profile and balance
• GET /me/subscriptions — subscriptions and links
• GET /me/balance/transactions — transaction history

Admin

• Users — CRUD, status approval (pending / active / rejected), balance management
• Tariffs — CRUD
• Nodes — CRUD, protocol management, xray/MTProto version install, GeoIP update, outbounds
• Subscriptions — create, manage, auto-renewal toggle
• Routing rule sets — xray-native rules and balancers
• External subscriptions — aggregate external VPN share URLs
• Audit logs

Tariff types

Type	Expiry	Auto-renews
Timed paid	By date	If balance ≥ 0
Timed free	By date	Always
Indefinite paid	When traffic exhausted	If balance ≥ 0
Indefinite free	When traffic exhausted	Always