Key Format
apm_<48 base62> (SHA-256)
RBAC Scopes
full, read + 12 Granular
Control Plane
7 API Domains + /enterprise
Telemetry & Events
HMAC Webhooks + Prometheus

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 with crypto.getRandomValues. The server combines that payload with two 32-character CSPRNG strings and a nanosecond timestamp via SHA-256, producing an apm_<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 the api_keys store.
  • 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 Control

Combine global or resource-level scopes to isolate billing bots, SRE monitors, and HR automation.

Scope / PatternAccess LevelTypical Operational Key Profile
fullUnrestricted read & write across all domains (Pro/Ultra/Extra)Master orchestrator or dedicated IaC controller
readGlobal read-only across resources (excluding /system/config)Centralized fleet observer or external BI dashboard
users:read / users:writeRead accounts & sessions / create, extend, revoke, kick & bulk opsTelegram & SaaS billing bots, HR/IAM onboarding
groups:read / groups:writeInspect user groups / assign and modify group policiesDepartment-based corporate access automation
plans:read / plans:writeList tariff plans / create/delete plans & apply traffic shaperCommercial tariff sync and bandwidth policy engine
webhooks:read / webhooks:writeList webhook targets / register or remove HMAC endpointsAutomated event-bus provisioning per tenant
monitoring:readAccess /overview, /health, /metrics, /sessions, /logs, /api-auditPrometheus scrapers, Grafana, SIEM & SOC collectors
system:read / system:writeSystem status / cascade mode, upstreams, services & security modeSRE 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 Surface

Every subsystem managed in the web UI is exposed for deterministic API automation.

DomainKey EndpointsCapabilities
Users & Bulk LifecycleGET/POST /users, GET /users/generate, POST /users/bulk-create, POST /users/bulk-extendCreate accounts, batch-provision fleets, and mass-extend quotas or TTLs
Per-User ControlGET /users/:id/config, POST /users/:id/extend|revoke|restore|reset-traffic|rotate-token|kick, PUT /users/:id/group|expiration|restrictions, GET /users/:id/sessionsFetch client configs, rotate tokens, kick live sessions, and tune per-user limits
Plans & ShaperGET/POST /plans, DELETE /plans/:id, POST /shaper/applyManage tariff templates and push live bandwidth/shaper rules
Cascade & UpstreamsPUT /cascade/mode, POST /upstreams/check, POST /upstreams/:id/toggle, POST /upstreams/:id/reset-trafficSwitch cascade routing modes, probe exit nodes, toggle upstreams, reset counters
Monitoring & AuditGET /overview, GET /health, GET /metrics, GET /sessions, POST /sessions/:id/kick, GET/DELETE /logs, POST /logs/simulate, GET /api-auditHealthchecks, Prometheus telemetry, live session termination, and API audit logs
Webhooks & KeysGET/POST /webhooks, DELETE /webhooks/:id, GET/POST /api-keys, DELETE /api-keys/:idProgrammatic lifecycle for HMAC webhook subscribers and scoped API keys
Services, Security & LicensePOST /services/toggle|restart|update-adblock|unban-ip|clear-auth-logs, PUT /settings/security-mode, GET /license/status, POST /license/activateDaemon control, Fail2ban IP unbanning, AdBlock updates, and license activation
Corporate GatewayGET /enterprise/overview, POST /enterprise/users/:id/toggle, .../enterprise/users/:id, .../enterprise/gateways/:idDedicated 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 Patterns

Common production architectures built on top of the Apium REST API, RBAC Keys, Webhooks, and Prometheus.

ScenarioAPI Primitives UsedOperational Benefit
Telegram Bots & SaaS Billingusers:write key + POST /users, /users/bulk-create, /extend, Subscriptions + WebhooksInstant key delivery after payment, automated renewals, zero manual admin work
Corporate HR / IAM Onboardingusers:write + groups:write + POST /users/:id/kick & /enterprise/...Automatic VPN access on hire and instant session revocation on offboarding
Fleet SRE & Monitoringmonitoring:read key + GET /metrics, /health, /api-audit + IP allowlistGrafana dashboards and alerts without exposing write permissions
Cascade & Shaper Automationsystem:write + plans:write + PUT /cascade/mode, POST /upstreams/check, POST /shaper/applyDynamic failover across exit countries and automated bandwidth enforcement