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 aveccrypto.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 jetonapm_<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 magasinapi_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èsCombinez des portées globales ou par ressource pour isoler les bots de facturation, les moniteurs SRE et l'automatisation RH.
| Portée / Motif | Niveau d'accès | Profil de clé opérationnel typique |
|---|---|---|
| full | Lecture & écriture sans restriction sur tous les domaines (Pro/Ultra/Extra) | Orchestrateur maître ou contrôleur IaC dédié |
| read | Lecture seule globale sur les ressources (hors /system/config) | Observateur de flotte centralisé ou tableau de bord BI externe |
| users:read / users:write | Lecture comptes & sessions / créer, prolonger, révoquer, éjecter & ops en masse | Bots de facturation Telegram & SaaS, onboarding RH/IAM |
| groups:read / groups:write | Inspecter les groupes d'utilisateurs / assigner et modifier les politiques de groupe | Automatisation d'accès d'entreprise par département |
| plans:read / plans:write | Lister les forfaits / créer/supprimer des forfaits & appliquer le shaper de trafic | Synchronisation des tarifs commerciaux et moteur de bande passante |
| webhooks:read / webhooks:write | Lister les cibles webhook / enregistrer ou supprimer les endpoints HMAC | Provisionnement automatisé du bus d'événements par locataire |
| monitoring:read | Accès à /overview, /health, /metrics, /sessions, /logs, /api-audit | Collecteurs 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 APIChaque sous-système géré dans l'interface Web est exposé pour une automatisation API déterministe.
| Domaine | Endpoints clés | Capacités |
|---|---|---|
| Utilisateurs & cycle de vie en masse | GET/POST /users, GET /users/generate, POST /users/bulk-create, POST /users/bulk-extend | Créer des comptes, provisionner des flottes par lots et prolonger en masse quotas ou TTL |
| Contrôle par utilisateur | 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 | Récupérer les configs clients, renouveler les jetons, éjecter les sessions actives et ajuster les limites |
| Forfaits & Shaper | GET/POST /plans, DELETE /plans/:id, POST /shaper/apply | Gérer les modèles de tarifs et pousser les règles bande passante/shaper en direct |
| Cascade & Amonts | PUT /cascade/mode, POST /upstreams/check, POST /upstreams/:id/toggle, POST /upstreams/:id/reset-traffic | Changer de mode de cascade, sonder les nœuds de sortie, activer/désactiver les amonts, réinitialiser les compteurs |
| Monitoring & Audit | GET /overview, GET /health, GET /metrics, GET /sessions, POST /sessions/:id/kick, GET/DELETE /logs, POST /logs/simulate, GET /api-audit | Contrôles de santé, télémétrie Prometheus, coupure de sessions en direct et journaux d'audit API |
| Webhooks & Clés | GET/POST /webhooks, DELETE /webhooks/:id, GET/POST /api-keys, DELETE /api-keys/:id | Cycle de vie programmatique des abonnés webhook HMAC et des clés API à portée limitée |
| Services, Sécurité & Licence | POST /services/toggle|restart|update-adblock|unban-ip|clear-auth-logs, PUT /settings/security-mode, GET /license/status, POST /license/activate | Contrôle des démons, débannissement IP Fail2ban, mises à jour AdBlock et activation de licence |
| Corporate Gateway | GET /enterprise/overview, POST /enterprise/users/:id/toggle, .../enterprise/users/:id, .../enterprise/gateways/:id | Control 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/extendB. 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=1798761600C. 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"} 185. Scénarios d'intégration réels
Où l'API Apium Cloud OS excelle
Schémas d'intégrationArchitectures de production courantes bâties sur l'API REST Apium, les clés RBAC, les Webhooks et Prometheus.
| Scénario | Primitives API utilisées | Bénéfice opérationnel |
|---|---|---|
| Bots Telegram & Facturation SaaS | Clé users:write + POST /users, /users/bulk-create, /extend, Subscriptions + Webhooks | Livraison instantanée de clé après paiement, renouvellements automatisés, zéro travail admin manuel |
| Onboarding RH / IAM d'entreprise | users: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 & Monitoring | Clé monitoring:read + GET /metrics, /health, /api-audit + liste blanche IP | Tableaux de bord Grafana et alertes sans exposer de permissions d'écriture |
| Automatisation Cascade & Shaper | system:write + plans:write + PUT /cascade/mode, POST /upstreams/check, POST /shaper/apply | Basculement dynamique entre pays de sortie et application automatisée de la bande passante |