Intégration de l'API REST CloudTAK : connecter des systèmes externes à votre réseau tactique

Par l'équipe d'ingénierie Corvus Intelligence · À propos de l'équipe →

29 mai 2026 12 min de lecture

L'API REST de CloudTAK transforme un serveur TAK d'un simple relais passif en un hub d'intégration actif. Plutôt que d'exiger de chaque source de données qu'elle parle CoT natif via TCP/TLS — le seul chemin vers le TAK Server hérité — CloudTAK expose une surface HTTP et WebSocket complète que tout système moderne peut appeler : réseaux de capteurs, plateformes logistiques, pipelines d'inférence IA, flux SIGINT et tableaux de bord personnalisés. Ce guide couvre en détail toutes les surfaces API majeures : authentification, injection CoT, streaming de tracks en temps réel, gestion des missions, upload de paquets de données, administration des groupes, webhooks et le copilote IA TAKpilot comme exemple d'intégration. Si vous devez d'abord configurer un serveur CloudTAK, consultez notre guide sur le déploiement du serveur CloudTAK.

Authentification : tokens JWT, clés API et portées

L'API REST CloudTAK applique l'authentification sur chaque point de terminaison sauf le contrôle de santé (GET /api/health). Deux types de credentials sont supportés, tous deux passés comme en-tête HTTP Authorization: Bearer <token>.

Tokens JWT

Les tokens JWT sont de courte durée et émis par session utilisateur. Obtenez-en un en envoyant des credentials au point de terminaison de connexion :

curl -s -X POST https://tak.yourdomain.com:8443/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "operator01", "password": "s3cur3p@ss"}' \
  | jq -r '.token'

Le TTL par défaut est 86400 secondes (24 heures) ; configurable via CLOUDTAK_JWT_TTL. Les JWT portent le rôle de l'utilisateur et les appartenances aux groupes comme claims, donc les vérifications de permissions sont sans état.

Clés API

Les clés API sont des tokens longue durée pour les intégrations automatisées service-à-service. Générez-les via l'API admin :

curl -s -X POST https://tak.yourdomain.com:8443/api/token \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sensor-array-east",
    "scopes": ["cot:write"],
    "rateLimit": 500
  }' | jq -r '.token'

Portées supportées et ce qu'elles débloquent :

Portée	Accorde l'accès à
`cot:write`	Injecter des événements CoT via POST /api/cot
`cot:read`	Interroger les tracks historiques via GET /api/cot
`events:subscribe`	Se connecter au stream WebSocket sur /api/ws
`mission:write`	Créer, mettre à jour et supprimer des missions
`package:write`	Téléverser des paquets de données et pièces jointes
`group:write`	Créer des groupes et gérer les adhésions
`admin`	Toutes les portées plus la gestion des utilisateurs et la configuration du serveur

Révoquez une clé à tout moment : DELETE /api/token/{id}. Listez les clés actives avec GET /api/token.

URL de base et limites de débit

Tous les points de terminaison REST sont servis sous https://<host>:8443/api/. La limite de débit globale par défaut est de 100 requêtes par seconde par clé API. Les réponses HTTP 429 incluent un en-tête Retry-After. La spécification OpenAPI est disponible sur GET /api/docs.

Injection CoT : POST /api/cot

Le point de terminaison d'injection CoT est le chemin principal pour pousser des rapports de position, marqueurs de contact, alertes et tout autre événement CoT dans le tableau tactique depuis des systèmes externes. Il accepte à la fois du CoT XML brut et un format JSON pratique.

Payload XML

Pour les systèmes qui génèrent déjà du CoT XML natif, envoyez directement l'enveloppe brute :

curl -s -X POST https://tak.yourdomain.com:8443/api/cot \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/xml" \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<event version="2.0"
       uid="sensor-east-001"
       type="a-f-G-U-C"
       how="m-g"
       time="2026-05-29T14:32:00Z"
       start="2026-05-29T14:32:00Z"
       stale="2026-05-29T14:37:00Z">
  <point lat="50.4501" lon="30.5234" hae="145.0" ce="10.0" le="5.0"/>
  <detail>
    <contact callsign="SENSOR-EAST-01"/>
    <remarks>Contact radar terrestre, vitesse 12 kph, cap 045</remarks>
    <group name="Surveillance" role="Team Member"/>
  </detail>
</event>'

Payload JSON

Pour les intégrations sur des stacks modernes sans bibliothèques CoT XML, utilisez le format JSON :

curl -s -X POST https://tak.yourdomain.com:8443/api/cot \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "logistics-truck-07",
    "type": "a-f-G-U-C",
    "callsign": "LOG-07",
    "lat": 50.4610,
    "lon": 30.5190,
    "hae": 138.0,
    "ce": 5.0,
    "le": 3.0,
    "staleSeconds": 300,
    "remarks": "Convoi de ravitaillement, ETA checkpoint 14:45Z",
    "group": "Logistics",
    "role": "Team Member"
  }'

CloudTAK sérialise ce JSON vers une enveloppe CoT XML complète en interne. Une injection réussie retourne HTTP 201. L'événement se propage immédiatement à tous les clients abonnés et au stream WebSocket.

Streaming de tracks : WebSocket /api/ws

Pour la consommation en temps réel du tableau tactique, le point de terminaison WebSocket fournit un stream continu et faible latence d'événements CoT.

Connexion et abonnement

// Exemple Node.js avec la bibliothèque 'ws'
const WebSocket = require('ws');

const ws = new WebSocket('wss://tak.yourdomain.com:8443/api/ws', {
  headers: { 'Authorization': `Bearer ${process.env.CLOUDTAK_API_KEY}` }
});

ws.on('open', () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    filter: {
      groups: ['Surveillance', 'Logistics'],
      bbox: [29.5, 50.0, 31.5, 51.0],
      types: ['a-f-G', 'a-h-G', 'a-u-G']
    }
  }));
});

ws.on('message', (data) => {
  const event = JSON.parse(data);
  if (event.type === 'cot') {
    console.log(`Track : ${event.payload.uid} à ${event.payload.lat},${event.payload.lon}`);
  } else if (event.type === 'ping') {
    ws.send(JSON.stringify({ type: 'pong' }));
  }
});

Le serveur envoie un message ping toutes les 30 secondes. Les clients doivent répondre avec pong dans les 10 secondes.

Mettre à jour les filtres sur une connexion active

Envoyez un nouveau message subscribe à tout moment pour remplacer le filtre actuel — sans déconnexion ni reconnexion.

API des missions : créer, mettre à jour, supprimer et assigner

Les missions dans CloudTAK sont des contextes opérationnels nommés qui regroupent tracks, paquets de données et utilisateurs. L'API des missions permet aux systèmes externes de créer des missions de façon programmatique.

Créer une mission

curl -s -X POST https://tak.yourdomain.com:8443/api/mission \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OPÉRATION CLEARWATER",
    "description": "Saisie de checkpoint, Phase 1",
    "classification": "UNCLASSIFIED",
    "bbox": [30.10, 50.35, 30.25, 50.45],
    "groups": ["Alpha-Company", "ISR-Detachment"]
  }' | jq '{uid: .uid, name: .name}'

La réponse inclut l'uid de mission (UUID). Mettez à jour les métadonnées avec PATCH /api/mission/{uid}. Supprimez avec DELETE /api/mission/{uid}.

API des paquets de données : MBTiles, KMZ, GeoJSON et versionnement

Les paquets de données attachés aux missions distribuent des couches cartographiques et des données de référence aux appareils de terrain. CloudTAK accepte trois formats : MBTiles, KMZ et GeoJSON :

# Téléverser une couche MBTiles pour la couverture cartographique hors ligne
curl -s -X POST \
  https://tak.yourdomain.com:8443/api/mission/${MISSION_UID}/attachment \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@/data/aoi-sector-north.mbtiles" \
  -F "name=Carte de base secteur nord" \
  -F "contentType=application/vnd.mbtiles" \
  | jq '{attachmentId: .id, version: .version}'

Les couches cartographiques autonomes sont téléversées via POST /api/layer. Pour les déploiements hors ligne : MBTiles et PMTiles pour les cartes hors ligne.

Groupes et canaux : filtrage de visibilité et contrôle d'accès aux tracks

Les groupes CloudTAK implémentent la ségrégation de visibilité des tracks. Un track portant un tag de groupe n'est visible que pour les clients connectés qui sont membres de ce groupe. Cela permet une séparation besoin-de-savoir au sein d'un serveur TAK partagé.

Créer un groupe et assigner des utilisateurs

# Créer un groupe
curl -s -X POST https://tak.yourdomain.com:8443/api/group \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ISR-Detachment", "description": "Cellule Renseignement, Surveillance, Reconnaissance"}' \
  | jq '.id'

# Ajouter un utilisateur au groupe
curl -s -X POST https://tak.yourdomain.com:8443/api/group/ISR-Detachment/user \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "isr-analyst-01"}'

Un client peut appartenir à plusieurs groupes simultanément. Les tracks sans tag de groupe sont visibles pour tous les utilisateurs du serveur.

TAKpilot comme exemple d'intégration

TAKpilot est le copilote IA de Corvus Intelligence pour les opérations basées sur TAK. C'est un exemple concret d'intégration profonde de l'API CloudTAK : TAKpilot s'abonne au stream de tracks WebSocket, traite des commandes en langage naturel des opérateurs et les exécute comme des appels API CloudTAK.

Une commande en langage naturel telle que "marquer la grille 38T YQ 45123 67890 comme contact hostile, assigner à la mission Alpha-Company" déclenche la séquence API suivante dans TAKpilot :

Convertir MGRS 38T YQ 45123 67890 en degrés décimaux (conversion interne, pas d'appel API).
POST /api/cot avec le type a-h-G (hostile terrestre), les coordonnées converties et un indicatif généré par le système préfixé AI-HOSTILE-.
GET /api/mission?name=Alpha-Company pour résoudre l'UID de mission.
POST /api/mission/{uid}/cot pour associer l'UID de l'événement CoT injecté à la mission.
Répondre à l'opérateur via l'interface de chat TAKpilot confirmant l'action.

TAKpilot utilise également le stream WebSocket de manière réactive : quand un nouveau track hostile (type a-h) apparaît dans un périmètre surveillé, il peut automatiquement déclencher une analyse de modèle de menace.

Webhooks : s'abonner aux événements et les transmettre aux systèmes externes

Les webhooks permettent à CloudTAK de pousser des événements vers des systèmes externes plutôt que d'exiger que ces systèmes interrogent l'API REST ou maintiennent une connexion WebSocket persistante.

Enregistrer un webhook

curl -s -X POST https://tak.yourdomain.com:8443/api/webhook \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "kafka-bridge",
    "url": "https://integration.yourdomain.com/cloudtak-events",
    "events": ["new_track", "mission_update", "user_join"],
    "secret": "hmac_signing_secret_32chars_min",
    "active": true
  }' | jq '{id: .id, status: .status}'

CloudTAK signe chaque livraison webhook avec une signature HMAC-SHA256 dans l'en-tête X-CloudTAK-Signature. Vérifiez la signature côté réception :

// Récepteur webhook Express.js avec vérification de signature
const crypto = require('crypto');

app.post('/cloudtak-events', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['x-cloudtak-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Signature invalide');
  }

  const event = JSON.parse(req.body);
  // Transmettre à Kafka, Slack, SIEM, etc.
  kafkaProducer.send({ topic: 'tak-events', messages: [{ value: req.body }] });
  res.status(200).send('OK');
});

Les échecs de livraison déclenchent des nouvelles tentatives avec backoff exponentiel : 1, 2, 4, 8, 16 secondes. Consulter l'historique des livraisons : GET /api/webhook/{id}/deliveries.

Types d'événements webhook supportés

new_track — un nouvel UID apparaît pour la première fois sur le tableau.
track_stale — le timestamp stale d'un track est passé sans mise à jour.
mission_update — une mission a été créée, modifiée, archivée ou supprimée.
user_join — un nouveau client s'est connecté et authentifié.
user_leave — un client s'est déconnecté ou la session a expiré.
cot_alert — un événement CoT avec le préfixe de type b-a (alerte) a été reçu.

Connectez vos systèmes à l'écosystème TAK

Nous construisons des intégrations API CloudTAK pour les réseaux de capteurs, plateformes logistiques, pipelines d'inférence IA et tableaux de bord C2 personnalisés — et les propulsons avec TAKpilot, notre copilote IA pour les opérations tactiques.

Copilote IA TAKpilot → Réserver un briefing

Cette analyse a été préparée par les ingénieurs de Corvus Intelligence qui développent des logiciels critiques pour les organisations de défense et gouvernementales. En savoir plus sur notre équipe →

Questions fréquentes

Quelles méthodes d'authentification l'API REST CloudTAK supporte-t-elle ?

L'API REST CloudTAK supporte deux méthodes d'authentification : les tokens JWT bearer et les clés API statiques. Les tokens JWT sont émis via POST /api/login et expirent après un TTL configurable (24 heures par défaut). Les clés API sont des tokens longue durée générés via l'API admin, adaptés aux intégrations service-à-service. Pour les intégrations en production, les clés API sont préférées car elles peuvent être limitées à des permissions spécifiques.

Quel est le Content-Type correct pour l'injection CoT via l'API REST ?

Le point de terminaison d'injection CoT CloudTAK (POST /api/cot) accepte deux types de contenu : application/xml pour les payloads CoT XML bruts, et application/json pour un wrapper JSON que CloudTAK convertit en CoT XML. Incluez toujours l'en-tête Content-Type explicitement.

Comment filtrer le stream de tracks WebSocket par groupe ou zone géographique ?

Le point de terminaison WebSocket CloudTAK (/api/ws) accepte un objet de filtre d'abonnement au moment de la connexion. Le filtre supporte trois champs : groups (tableau de noms de groupes), bbox (boîte englobante GeoJSON [minLon, minLat, maxLon, maxLat]) et types (tableau de chaînes de types CoT). Vous pouvez mettre à jour les filtres sur une connexion active.

Quelle est la limite de débit sur le point de terminaison d'injection CoT ?

La limite de débit CloudTAK par défaut est de 100 événements CoT par seconde par clé API. Configurable via la variable d'environnement CLOUDTAK_COT_RATE_LIMIT ou par clé via l'API admin. Si votre intégration dépasse la limite, l'API retourne HTTP 429 Too Many Requests avec un en-tête Retry-After.

Comment créer une mission et y attacher des paquets de données via l'API ?

La création de mission est un processus en deux étapes : d'abord POST vers /api/mission avec un nom, une description et une attribution de groupe optionnelle pour obtenir un UID de mission. Puis POST vers /api/mission/{uid}/attachment avec un corps multipart/form-data contenant le fichier de paquet de données (MBTiles, KMZ ou GeoJSON).

Puis-je téléverser des couches cartographiques MBTiles via l'API CloudTAK ?

Oui. POST vers /api/layer avec un corps multipart/form-data contenant le fichier MBTiles et les métadonnées (name, minZoom, maxZoom, bounds). CloudTAK valide le format MBTiles et rend la couche disponible pour tous les clients connectés. PMTiles est également supporté via le même point de terminaison.

Comment fonctionnent les webhooks dans CloudTAK ?

Les webhooks CloudTAK sont enregistrés via POST /api/webhook avec une URL cible, des types d'événements et un secret HMAC optionnel. En cas d'échec de livraison, CloudTAK réessaie avec backoff exponentiel jusqu'à 5 fois.

Comment TAKpilot utilise-t-il l'API CloudTAK pour exécuter des commandes en langage naturel ?

TAKpilot reçoit des commandes en langage naturel des opérateurs et les décompose en appels API CloudTAK. Une commande pour marquer un emplacement devient un POST /api/cot avec le type CoT approprié. TAKpilot maintient un contexte de session et consomme également le stream WebSocket de façon réactive.

Quels types d'événements puis-je souscrire via le WebSocket CloudTAK ?

Le stream WebSocket CloudTAK émet cinq types d'événements : cot (un événement CoT XML), track_update (une mise à jour delta d'un track existant), mission_update (une mission a été créée, modifiée ou supprimée), user_event (un client s'est connecté, déconnecté ou a changé d'indicatif) et system_event (événements côté serveur). Souscrivez sélectivement en utilisant le champ de filtre types.

Comment versionner les paquets de données attachés aux missions ?

CloudTAK maintient un historique de versions pour chaque pièce jointe de paquet de données. Chaque upload vers /api/mission/{uid}/attachment crée une nouvelle version. La version actuelle est servie par défaut. Pour récupérer une version spécifique, ajoutez le paramètre de requête version : GET /api/mission/{uid}/attachment/{attachmentId}?version=2.