1. Autentisering, nyckelgenerering & säkerhetskontroller
Varje Apium Cloud OS-nod exponerar sitt kontrollplan under en isolerad konsolsökväg (/<console>/api/v1/...). Förfrågningar accepterar autentiseringsuppgifter via antingen X-API-Key: apm_... eller Authorization: Bearer apm_....
- Nyckelgenerering med hybrid-entropi: När en nyckel utfärdas i gränssnittet samlar webbläsaren in musrörelsekoordinater och tidpunkter (
client_entropy) blandat medcrypto.getRandomValues. Servern kombinerar den nyttolasten med två 32-teckens CSPRNG-strängar och en nanosekund-tidsstämpel via SHA-256, vilket producerar enapm_<48 base62>-token. - Engångsvisning i klartext & hashad lagring: Den råa
apm_...-token visas exakt en gång vid skapandet. Endast dess SHA-256-hash lagras iapi_keys-lagret. - Nätverks- & livstidsbegränsningar: Varje nyckel stöder en IP-allowlist (
allowed_ips) och en automatisk utgångstidsstämpel (expires_at). - Granskningslogg & OpenAPI: Varje API-anrop registreras i granskningsloggen (
GET /api/v1/api-audit), och noden exporterar en maskinläsbar OpenAPI-specifikation (apium-cloud-os-openapi.json) för SDK-generering.
2. RBAC-behörighetsmatris & licensnivåer
Istället för allt-eller-inget-admintokens upprätthåller Apium Cloud OS principen om minsta privilegium via kommaseparerade behörigheter (scopes). På den kostnadsfria utgåvan Lite tillåts endast read-åtkomst; full och alla skrivbehörigheter kräver Pro, Ultra eller Extra.
API-nyckelbehörigheter & profiler för minsta privilegium
ÅtkomstkontrollKombinera globala eller resursnivåbehörigheter för att isolera faktureringsbotar, SRE-övervakare och HR-automatisering.
| Scope / Mönster | Åtkomstnivå | Typisk operativ nyckelprofil |
|---|---|---|
| full | Obegränsad läsning & skrivning över alla domäner (Pro/Ultra/Extra) | Masterorkestrator eller dedikerad IaC-kontroller |
| read | Global skrivskyddad åtkomst över resurser (exklusive /system/config) | Centraliserad flottobservatör eller extern BI-panel |
| users:read / users:write | Läsa konton & sessioner / skapa, förlänga, återkalla, kasta ut & bulk-operationer | Telegram- & SaaS-faktureringsbotar, HR/IAM-onboarding |
| groups:read / groups:write | Inspektera användargrupper / tilldela och ändra gruppolicyer | Avdelningsbaserad företagsåtkomstautomatisering |
| plans:read / plans:write | Lista tariffplaner / skapa/ta bort planer & tillämpa trafikshaper | Kommersiell tariffsynkronisering och bandbreddspolicymotor |
| webhooks:read / webhooks:write | Lista webhook-mål / registrera eller ta bort HMAC-endpoints | Automatiserad händelsebuss-provisionering per hyresgäst |
| monitoring:read | Åtkomst till /overview, /health, /metrics, /sessions, /logs, /api-audit | Prometheus-scrapers, Grafana, SIEM & SOC-insamlare |
| system:read / system:write | Systemstatus / kaskadläge, uppströms, tjänster & säkerhetsläge | SRE-failoverautomatisering & livscykelskript för tjänster |
3. Komplett endpointkarta över 7 kontrolldomäner
Alla administrativa rutter finns under /<console>/api/v1 och täcker nodens fulla operativa yta:
Endpoints grupperade efter funktionell domän
API-ytaVarje delsystem som hanteras i webbgränssnittet exponeras för deterministisk API-automatisering.
| Domän | Viktiga endpoints | Kapacitet |
|---|---|---|
| Användare & bulklivscykel | GET/POST /users, GET /users/generate, POST /users/bulk-create, POST /users/bulk-extend | Skapa konton, batch-provisionera flottor och massförlänga kvoter eller TTL |
| Kontroll per användare | 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 | Hämta klientkonfigurationer, rotera tokens, kasta ut aktiva sessioner och finjustera gränser per användare |
| Planer & shaper | GET/POST /plans, DELETE /plans/:id, POST /shaper/apply | Hantera tariffmallar och skicka ut live-regler för bandbredd/shaper |
| Kaskad & uppströms | PUT /cascade/mode, POST /upstreams/check, POST /upstreams/:id/toggle, POST /upstreams/:id/reset-traffic | Växla kaskadroutinglägen, proba utgångsnoder, slå på/av uppströms, nollställ räknare |
| Övervakning & granskning | GET /overview, GET /health, GET /metrics, GET /sessions, POST /sessions/:id/kick, GET/DELETE /logs, POST /logs/simulate, GET /api-audit | Hälsokontroller, Prometheus-telemetri, avslutning av livesessioner och API-granskningsloggar |
| Webhooks & nycklar | GET/POST /webhooks, DELETE /webhooks/:id, GET/POST /api-keys, DELETE /api-keys/:id | Programmatisk livscykel för HMAC-webhookprenumeranter och behörighetsstyrda API-nycklar |
| Tjänster, säkerhet & licens | POST /services/toggle|restart|update-adblock|unban-ip|clear-auth-logs, PUT /settings/security-mode, GET /license/status, POST /license/activate | Demonkontroll, avblockering av IP i Fail2ban, AdBlock-uppdateringar och licensaktivering |
| Corporate Gateway | GET /enterprise/overview, POST /enterprise/users/:id/toggle, .../enterprise/users/:id, .../enterprise/gateways/:id | Dedikerat kontrollplan för Corporate Gateway-användare och gatewaynoder |
4. Praktiska exempel på förfrågningar & händelser
A. Bulk-provisionering & förlängning av användare
Skapa konton bundna till en tariffplan (plan_id), kör batch-provisionering eller förläng prenumerationer med automatisk återställning (auto_restore: true) utan att starta om transportkärnor:
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. Publik prenumerations-endpoint (standardiserade klientheaders)
Klientappar som v2rayNG, Nekobox, Streisand och Hiddify hämtar en enda tokeniserad URL som returnerar Base64-profiler tillsammans med standardheaders för kvot och utgångstid:
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-signerade webhooks
Istället för att polla noden med några sekunders mellanrum, konfigurera din faktureringsbackend eller ditt CRM att ta emot push-händelser i realtid verifierade med 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-metrik (GET /api/v1/metrics)
Koppla in din flotta direkt till Prometheus och Grafana med en monitoring:read-nyckel för att spåra aktiva sessioner, användarantal och RTT för uppströms-kaskader:
# 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. Verkliga integrationsscenarier
Där Apium Cloud OS API briljerar
IntegrationsmönsterVanliga produktionsarkitekturer byggda ovanpå Apium REST API, RBAC-nycklar, Webhooks och Prometheus.
| Scenario | Använda API-primitiver | Operativ fördel |
|---|---|---|
| Telegram-botar & SaaS-fakturering | users:write-nyckel + POST /users, /users/bulk-create, /extend, Subscriptions + Webhooks | Omedelbar nyckelleverans efter betalning, automatiska förnyelser, noll manuellt adminarbete |
| Företags HR / IAM-onboarding | users:write + groups:write + POST /users/:id/kick & /enterprise/... | Automatisk VPN-åtkomst vid anställning och omedelbar återkallelse av sessioner vid avslut |
| Flott-SRE & övervakning | monitoring:read-nyckel + GET /metrics, /health, /api-audit + IP-allowlist | Grafana-paneler och larm utan att exponera skrivrättigheter |
| Kaskad- & shaperautomatisering | system:write + plans:write + PUT /cascade/mode, POST /upstreams/check, POST /shaper/apply | Dynamisk failover över utgångsländer och automatiserad bandbreddsstyrning |