1. Authentication, Key Generation & Security Controls
Every Apium Cloud OS node exposes its control plane under an isolated console path (/<console>/api/v1/...). Requests accept credentials via either X-API-Key: apm_... or Authorization: Bearer apm_....
- Hybrid-Entropy Key Generation: When issuing a key in the UI, the browser collects mouse-movement coordinates and timings (
client_entropy) mixed withcrypto.getRandomValues. The server combines that payload with two 32-character CSPRNG strings and a nanosecond timestamp via SHA-256, producing anapm_<48 base62>token. - One-Time Plaintext & Hashed Storage: The raw
apm_...token is displayed exactly once upon creation. Only its SHA-256 digest is persisted in theapi_keysstore. - Network & Lifetime Guardrails: Every key supports an IP allowlist (
allowed_ips) and an automatic expiration timestamp (expires_at). - Audit Trail & OpenAPI: Every API call is recorded in the audit log (
GET /api/v1/api-audit), and the node exports a machine-readable OpenAPI specification (apium-cloud-os-openapi.json) for SDK generation.
2. RBAC Scope Matrix & License Tiers
Instead of all-or-nothing admin tokens, Apium Cloud OS enforces least-privilege access via comma-separated scopes. On the free Lite edition, only read access is permitted; full and all write scopes require Pro, Ultra, or Extra.
API Key Scopes & Least-Privilege Profiles
Access ControlCombine global or resource-level scopes to isolate billing bots, SRE monitors, and HR automation.
| Scope / Pattern | Access Level | Typical Operational Key Profile |
|---|---|---|
| full | Unrestricted read & write across all domains (Pro/Ultra/Extra) | Master orchestrator or dedicated IaC controller |
| read | Global read-only across resources (excluding /system/config) | Centralized fleet observer or external BI dashboard |
| users:read / users:write | Read accounts & sessions / create, extend, revoke, kick & bulk ops | Telegram & SaaS billing bots, HR/IAM onboarding |
| groups:read / groups:write | Inspect user groups / assign and modify group policies | Department-based corporate access automation |
| plans:read / plans:write | List tariff plans / create/delete plans & apply traffic shaper | Commercial tariff sync and bandwidth policy engine |
| webhooks:read / webhooks:write | List webhook targets / register or remove HMAC endpoints | Automated event-bus provisioning per tenant |
| monitoring:read | Access /overview, /health, /metrics, /sessions, /logs, /api-audit | Prometheus scrapers, Grafana, SIEM & SOC collectors |
| system:read / system:write | System status / cascade mode, upstreams, services & security mode | SRE failover automation & service lifecycle scripts |
3. Complete Endpoint Map Across 7 Control Domains
All administrative routes live under /<console>/api/v1 and cover the full operational surface of the node:
Endpoints Grouped by Functional Domain
API SurfaceEvery subsystem managed in the web UI is exposed for deterministic API automation.
| Domain | Key Endpoints | Capabilities |
|---|---|---|
| Users & Bulk Lifecycle | GET/POST /users, GET /users/generate, POST /users/bulk-create, POST /users/bulk-extend | Create accounts, batch-provision fleets, and mass-extend quotas or TTLs |
| Per-User Control | GET /users/:id/config, POST /users/:id/extend|revoke|restore|reset-traffic|rotate-token|kick, PUT /users/:id/group|expiration|restrictions, GET /users/:id/sessions | Fetch client configs, rotate tokens, kick live sessions, and tune per-user limits |
| Plans & Shaper | GET/POST /plans, DELETE /plans/:id, POST /shaper/apply | Manage tariff templates and push live bandwidth/shaper rules |
| Cascade & Upstreams | PUT /cascade/mode, POST /upstreams/check, POST /upstreams/:id/toggle, POST /upstreams/:id/reset-traffic | Switch cascade routing modes, probe exit nodes, toggle upstreams, reset counters |
| Monitoring & Audit | GET /overview, GET /health, GET /metrics, GET /sessions, POST /sessions/:id/kick, GET/DELETE /logs, POST /logs/simulate, GET /api-audit | Healthchecks, Prometheus telemetry, live session termination, and API audit logs |
| Webhooks & Keys | GET/POST /webhooks, DELETE /webhooks/:id, GET/POST /api-keys, DELETE /api-keys/:id | Programmatic lifecycle for HMAC webhook subscribers and scoped API keys |
| Services, Security & License | POST /services/toggle|restart|update-adblock|unban-ip|clear-auth-logs, PUT /settings/security-mode, GET /license/status, POST /license/activate | Daemon control, Fail2ban IP unbanning, AdBlock updates, and license activation |
| Corporate Gateway | GET /enterprise/overview, POST /enterprise/users/:id/toggle, .../enterprise/users/:id, .../enterprise/gateways/:id | Dedicated control plane for Corporate Gateway users and gateway nodes |
4. Practical Request & Event Examples
A. Bulk User Provisioning & Extension
Create accounts bound to a tariff plan (plan_id), run batch provisioning, or extend subscriptions with automatic restoration (auto_restore: true) without restarting transport cores:
curl -X POST -H "X-API-Key: apm_..." \
-H "Content-Type: application/json" \
-d '{"username":"client_9042","plan_id":1}' \
https://node.apium.cloud/<console>/api/v1/users
curl -X POST -H "Authorization: Bearer apm_..." \
-H "Content-Type: application/json" \
-d '{"add_days":30,"add_quota_gb":100,"auto_restore":true}' \
https://node.apium.cloud/<console>/api/v1/users/42/extend
B. Public Subscription Endpoint (Standard Client Headers)
Client apps such as v2rayNG, Nekobox, Streisand, and Hiddify fetch a single tokenized URL that returns Base64 profiles along with standard quota and expiration headers:
GET /<console>/api/v1/subscriptions/<sub_token>
< HTTP/1.1 200 OK
< Profile-Title: Apium Cloud OS
< Profile-Update-Interval: 12
< Subscription-Userinfo: upload=104857600; download=2147483648; total=107374182400; expire=1798761600
C. HMAC-SHA256 Signed Webhooks
Instead of polling the node every few seconds, configure your billing backend or CRM to receive real-time push events verified by X-Apium-Signature:
POST https://billing.example.com/webhooks/apium
X-Apium-Event: user.created
X-Apium-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
{
"event": "user.created",
"timestamp": "2026-11-14T12:30:00Z",
"data": { "user": { "id": 42, "username": "client_9042", "protocol": "hysteria2" } }
}
D. Prometheus Metrics (GET /api/v1/metrics)
Plug your fleet directly into Prometheus and Grafana with a monitoring:read key to track active sessions, user counts, and upstream cascade RTTs:
# TYPE apium_active_sessions gauge
apium_active_sessions 1248
# TYPE apium_users_total gauge
apium_users_total{status="active"} 3410
# TYPE apium_upstream_latency_ms gauge
apium_upstream_latency_ms{id="1",name="NL-AMS-01"} 18
5. Real-World Integration Scenarios
Where the Apium Cloud OS API Excels
Integration PatternsCommon production architectures built on top of the Apium REST API, RBAC Keys, Webhooks, and Prometheus.
| Scenario | API Primitives Used | Operational Benefit |
|---|---|---|
| Telegram Bots & SaaS Billing | users:write key + POST /users, /users/bulk-create, /extend, Subscriptions + Webhooks | Instant key delivery after payment, automated renewals, zero manual admin work |
| Corporate HR / IAM Onboarding | users:write + groups:write + POST /users/:id/kick & /enterprise/... | Automatic VPN access on hire and instant session revocation on offboarding |
| Fleet SRE & Monitoring | monitoring:read key + GET /metrics, /health, /api-audit + IP allowlist | Grafana dashboards and alerts without exposing write permissions |
| Cascade & Shaper Automation | system:write + plans:write + PUT /cascade/mode, POST /upstreams/check, POST /shaper/apply | Dynamic failover across exit countries and automated bandwidth enforcement |