# 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`](./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 |