Deploy Tokens & Mass Deployment

Programmatic node provisioning for fleets of any size

Deploy Tokens vs API Keys

Flowtriq uses two types of credentials. They serve different purposes and should not be confused:

Credential	Scope	Purpose	Who holds it
Deploy Token	Workspace-wide	Create new nodes via the `/api/deploy` endpoint. Cannot read data, send metrics, or manage existing nodes.	DevOps / automation tools
API Key	Per-node	Authenticate the ftagent running on a specific server. Used for sending metrics, heartbeats, and incident data. One key per node.	Each individual server (in `/etc/ftagent/config.json`)
API Token	Workspace-wide (scoped)	Full REST API access with optional scope restrictions. Read/write nodes, incidents, channels, analytics. Created in Dashboard → Settings → API Tokens.	External integrations, SIEM connectors, custom dashboards

Creating Deploy Tokens

Go to Dashboard → Settings → Workspace and find the Mass Deployment Token card. Click Generate Deploy Token.

Your token is a 64-character hex string. Treat it like a password. Anyone with the token can create nodes in your workspace and increase your bill.

Security: Store your deploy token in environment variables or a secrets manager (Vault, AWS Secrets Manager, 1Password CLI). Never commit it to version control. Revoke it immediately from Settings if compromised.

One-Liner Deployment Script

Run this single command as root on any Linux server. It registers the node, installs ftagent, writes the config, enables the systemd service, and starts monitoring:

# Full deploy: register + install + configure + enable + start
bash -c 'R=$(curl -sf https://flowtriq.com/api/deploy \
  -H "Authorization: Bearer $FLOWTRIQ_DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"$(hostname)\",\"ip\":\"$(curl -s ifconfig.me)\"}") \
  && eval $(echo "$R" | python3 -c "import sys,json;d=json.load(sys.stdin);print(\"API_KEY=\"+d[\"api_key\"]+\" NODE_UUID=\"+d[\"node_uuid\"])") \
  && pip install ftagent --break-system-packages -q \
  && mkdir -p /etc/ftagent /var/lib/ftagent/pcaps \
  && echo "{\"api_key\":\"$API_KEY\",\"api_base\":\"https://flowtriq.com/api/v1\",\"node_uuid\":\"$NODE_UUID\",\"interface\":\"eth0\"}" > /etc/ftagent/config.json \
  && chmod 600 /etc/ftagent/config.json \
  && ftagent --install-service \
  && systemctl enable ftagent \
  && systemctl start ftagent \
  && echo "Done - node registered and ftagent running"'

Deploy API Reference

POST https://flowtriq.com/api/deploy
Authorization: Bearer YOUR_DEPLOY_TOKEN
Content-Type: application/json

{
  "name": "web-prod-3",
  "ip": "203.0.113.10",
  "location": "US-East",
  "os": "Ubuntu 24.04",
  "interface": "eth0"
}

Field	Required	Description
name	Yes	Unique node name within your workspace
ip	Yes	IPv4 or IPv6 address of the server
location	No	Data center or region label
os	No	Operating system string
interface	No	Network interface to monitor (default: eth0)

Response

{
  "ok": true,
  "node_uuid": "a1b2c3d4-...",
  "api_key": "64-char-hex-api-key-for-this-node",
  "name": "web-prod-3",
  "ip": "203.0.113.10"
}

Ansible Playbook

# deploy-flowtriq.yml
- hosts: all
  vars:
    flowtriq_token: "{{ lookup('env', 'FLOWTRIQ_DEPLOY_TOKEN') }}"
  tasks:
    - name: Register node with Flowtriq
      uri:
        url: https://flowtriq.com/api/deploy
        method: POST
        headers:
          Authorization: "Bearer {{ flowtriq_token }}"
          Content-Type: application/json
        body_format: json
        body:
          name: "{{ inventory_hostname }}"
          ip: "{{ ansible_default_ipv4.address }}"
          os: "{{ ansible_distribution }} {{ ansible_distribution_version }}"
          location: "{{ datacenter | default('') }}"
        status_code: 200
      register: flowtriq_result

    - name: Install ftagent
      pip:
        name: ftagent
        extra_args: --break-system-packages

    - name: Create config directory
      file:
        path: "{{ item }}"
        state: directory
        mode: '0755'
      loop:
        - /etc/ftagent
        - /var/lib/ftagent/pcaps

    - name: Write ftagent config
      copy:
        content: |
          {"api_key":"{{ flowtriq_result.json.api_key }}","api_base":"https://flowtriq.com/api/v1","node_uuid":"{{ flowtriq_result.json.node_uuid }}","interface":"eth0"}
        dest: /etc/ftagent/config.json
        mode: '0600'

    - name: Install systemd service
      command: ftagent --install-service

    - name: Enable and start ftagent
      systemd:
        name: ftagent
        enabled: true
        state: started
        daemon_reload: true

Cloud-Init / User Data

Add this to your EC2 user data, GCP startup script, or any cloud-init configuration to auto-register on first boot:

#!/bin/bash
# cloud-init / user-data script
DEPLOY_TOKEN="your-deploy-token-here"

# Register with Flowtriq
RESULT=$(curl -sf https://flowtriq.com/api/deploy \
  -H "Authorization: Bearer $DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"$(hostname)\",\"ip\":\"$(curl -s ifconfig.me)\"}")

API_KEY=$(echo "$RESULT" | python3 -c "import sys,json;print(json.load(sys.stdin)['api_key'])")
NODE_UUID=$(echo "$RESULT" | python3 -c "import sys,json;print(json.load(sys.stdin)['node_uuid'])")

# Install agent and write config
pip install ftagent --break-system-packages -q
mkdir -p /etc/ftagent /var/lib/ftagent/pcaps
cat > /etc/ftagent/config.json <<EOF
{"api_key":"$API_KEY","api_base":"https://flowtriq.com/api/v1","node_uuid":"$NODE_UUID","interface":"eth0"}
EOF
chmod 600 /etc/ftagent/config.json

# Install service, enable on boot, and start
ftagent --install-service
systemctl enable ftagent
systemctl start ftagent

Tagging Nodes on Deployment

Use the location and os fields to tag nodes during provisioning. These appear in the dashboard and can be used for filtering and grouping:

# Tag with datacenter region and OS
curl -sf https://flowtriq.com/api/deploy \
  -H "Authorization: Bearer $FLOWTRIQ_DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "'"$(hostname)"'",
    "ip": "'"$(curl -s ifconfig.me)"'",
    "location": "eu-west-1",
    "os": "'"$(lsb_release -ds 2>/dev/null || cat /etc/os-release | grep PRETTY_NAME | cut -d= -f2 | tr -d \\\")"'"
  }'

Bash Loop (Bulk Register)

#!/bin/bash
# servers.txt format: name,ip
# web-prod-1,203.0.113.10
# web-prod-2,203.0.113.11

while IFS=, read -r name ip; do
  echo "Registering $name ($ip)..."
  curl -s https://flowtriq.com/api/deploy \
    -H "Authorization: Bearer $FLOWTRIQ_DEPLOY_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"name\":\"$name\",\"ip\":\"$ip\"}" | jq '{name:.name, api_key:.api_key}'
done < servers.txt

Error Codes

HTTP	Error	Meaning
401	Invalid deploy token	Token is wrong, revoked, or missing
400	Node name / IP required	Missing required fields
402	Payment failed	No active subscription or payment issue
409	Duplicate name	A node with that name already exists in this workspace