Format de clé
apm_<48 base62> (SHA-256)
Portées RBAC
full, read + 12 granulaires
Control Plane
7 domaines API + /enterprise
Télémétrie & Événements
Webhooks HMAC + Prometheus

1. Authentification, génération de clés & contrôles de sécurité

Chaque nœud Apium Cloud OS expose son control plane sous un chemin de console isolé (/<console>/api/v1/...). Les requêtes acceptent les identifiants via X-API-Key: apm_... ou Authorization: Bearer apm_....

  • Génération de clé à entropie hybride : lors de l'émission d'une clé dans l'interface, le navigateur collecte les coordonnées et timings des mouvements de souris (client_entropy) mélangés avec crypto.getRandomValues. Le serveur combine cette charge utile avec deux chaînes CSPRNG de 32 caractères et un horodatage à la nanoseconde via SHA-256, produisant un jeton apm_<48 base62>.
  • Affichage unique en clair & stockage haché : le jeton brut apm_... est affiché exactement une fois lors de la création. Seul son condensat SHA-256 est conservé dans le magasin api_keys.
  • Garde-fous réseau & durée de vie : chaque clé prend en charge une liste blanche IP (allowed_ips) et un horodatage d'expiration automatique (expires_at).
  • Piste d'audit & OpenAPI : chaque appel API est enregistré dans le journal d'audit (GET /api/v1/api-audit), et le nœud exporte une spécification OpenAPI exploitable par machine (apium-cloud-os-openapi.json) pour la génération de SDK.

2. Matrice de portées RBAC & paliers de licence

Au lieu de jetons admin tout-ou-rien, Apium Cloud OS applique le moindre privilège via des portées séparées par des virgules. Sur l'édition gratuite Lite, seul l'accès read est autorisé ; full et toutes les portées d'écriture nécessitent Pro, Ultra ou Extra.

Portées de clé API & profils moindre privilège

Contrôle d'accès

Combinez des portées globales ou par ressource pour isoler les bots de facturation, les moniteurs SRE et l'automatisation RH.

Portée / MotifNiveau d'accèsProfil de clé opérationnel typique
fullLecture & écriture sans restriction sur tous les domaines (Pro/Ultra/Extra)Orchestrateur maître ou contrôleur IaC dédié
readLecture seule globale sur les ressources (hors /system/config)Observateur de flotte centralisé ou tableau de bord BI externe
users:read / users:writeLecture comptes & sessions / créer, prolonger, révoquer, éjecter & ops en masseBots de facturation Telegram & SaaS, onboarding RH/IAM
groups:read / groups:writeInspecter les groupes d'utilisateurs / assigner et modifier les politiques de groupeAutomatisation d'accès d'entreprise par département
plans:read / plans:writeLister les forfaits / créer/supprimer des forfaits & appliquer le shaper de traficSynchronisation des tarifs commerciaux et moteur de bande passante
webhooks:read / webhooks:writeLister les cibles webhook / enregistrer ou supprimer les endpoints HMACProvisionnement automatisé du bus d'événements par locataire
monitoring:readAccès à /overview, /health, /metrics, /sessions, /logs, /api-auditCollecteurs Prometheus, Grafana, SIEM & SOC
system:read / system:writeÉtat système / mode cascade, amonts, services & mode sécuritéAutomatisation de basculement SRE & scripts de cycle de vie des services

3. Carte complète des endpoints sur 7 domaines de contrôle

Toutes les routes d'administration résident sous /<console>/api/v1 et couvrent toute la surface opérationnelle du nœud :

Endpoints regroupés par domaine fonctionnel

Surface API

Chaque sous-système géré dans l'interface Web est exposé pour une automatisation API déterministe.

DomaineEndpoints clésCapacités
Utilisateurs & cycle de vie en masseGET/POST /users, GET /users/generate, POST /users/bulk-create, POST /users/bulk-extendCréer des comptes, provisionner des flottes par lots et prolonger en masse quotas ou TTL
Contrôle par utilisateurGET /users/:id/config, POST /users/:id/extend|revoke|restore|reset-traffic|rotate-token|kick, PUT /users/:id/group|expiration|restrictions, GET /users/:id/sessionsRécupérer les configs clients, renouveler les jetons, éjecter les sessions actives et ajuster les limites
Forfaits & ShaperGET/POST /plans, DELETE /plans/:id, POST /shaper/applyGérer les modèles de tarifs et pousser les règles bande passante/shaper en direct
Cascade & AmontsPUT /cascade/mode, POST /upstreams/check, POST /upstreams/:id/toggle, POST /upstreams/:id/reset-trafficChanger de mode de cascade, sonder les nœuds de sortie, activer/désactiver les amonts, réinitialiser les compteurs
Monitoring & AuditGET /overview, GET /health, GET /metrics, GET /sessions, POST /sessions/:id/kick, GET/DELETE /logs, POST /logs/simulate, GET /api-auditContrôles de santé, télémétrie Prometheus, coupure de sessions en direct et journaux d'audit API
Webhooks & ClésGET/POST /webhooks, DELETE /webhooks/:id, GET/POST /api-keys, DELETE /api-keys/:idCycle de vie programmatique des abonnés webhook HMAC et des clés API à portée limitée
Services, Sécurité & LicencePOST /services/toggle|restart|update-adblock|unban-ip|clear-auth-logs, PUT /settings/security-mode, GET /license/status, POST /license/activateContrôle des démons, débannissement IP Fail2ban, mises à jour AdBlock et activation de licence
Corporate GatewayGET /enterprise/overview, POST /enterprise/users/:id/toggle, .../enterprise/users/:id, .../enterprise/gateways/:idControl plane dédié pour les utilisateurs Corporate Gateway et les nœuds de passerelle

4. Exemples pratiques de requêtes & d'événements

A. Provisionnement & prolongation d'utilisateurs en masse

Créez des comptes liés à un forfait (plan_id), lancez un provisionnement par lot ou prolongez des abonnements avec restauration automatique (auto_restore: true) sans redémarrer les cœurs de transport :

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. Endpoint d'abonnement public (en-têtes clients standard)

Les applications clientes telles que v2rayNG, Nekobox, Streisand et Hiddify récupèrent une URL unique à jeton qui renvoie des profils Base64 ainsi que les en-têtes standard de quota et d'expiration :

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. Webhooks signés HMAC-SHA256

Au lieu d'interroger le nœud toutes les quelques secondes, configurez votre backend de facturation ou CRM pour recevoir des événements push en temps réel vérifiés par 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. Métriques Prometheus (GET /api/v1/metrics)

Branchez votre flotte directement sur Prometheus et Grafana avec une clé monitoring:read pour suivre les sessions actives, le nombre d'utilisateurs et les RTT de la cascade amont :

# 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. Scénarios d'intégration réels

Où l'API Apium Cloud OS excelle

Schémas d'intégration

Architectures de production courantes bâties sur l'API REST Apium, les clés RBAC, les Webhooks et Prometheus.

ScénarioPrimitives API utiliséesBénéfice opérationnel
Bots Telegram & Facturation SaaSClé users:write + POST /users, /users/bulk-create, /extend, Subscriptions + WebhooksLivraison instantanée de clé après paiement, renouvellements automatisés, zéro travail admin manuel
Onboarding RH / IAM d'entrepriseusers:write + groups:write + POST /users/:id/kick & /enterprise/...Accès VPN automatique à l'embauche et révocation instantanée des sessions au départ
SRE de flotte & MonitoringClé monitoring:read + GET /metrics, /health, /api-audit + liste blanche IPTableaux de bord Grafana et alertes sans exposer de permissions d'écriture
Automatisation Cascade & Shapersystem:write + plans:write + PUT /cascade/mode, POST /upstreams/check, POST /shaper/applyBasculement dynamique entre pays de sortie et application automatisée de la bande passante