Partner Integration Guide

Technical guide for Flowtriq reseller and white-label partners. Covers deploying ftagent under your brand, provisioning via API, and how alerts flow to your customers.

Architecture Overview

Flowtriq uses a multi-tenant model designed for partners. Your workspace is the parent workspace, and each of your customers gets a sub-workspace beneath it. This gives you a single pane of glass across your entire customer base while keeping each customer fully isolated.

Parent workspace: Your partner account. You manage billing, branding, and API tokens here.
Sub-workspaces: One per customer. Each sub-workspace has its own nodes, incidents, alerts, users, and thresholds. Customers in one sub-workspace cannot see data from another.
Partner Overview API: Your parent workspace can query aggregate stats across all sub-workspaces via GET /api/v1/partner/overview.

# Tenant hierarchy

Partner Workspace (your account)
├── Sub-Workspace A (Customer A)
│   ├── node: web-server-01
│   ├── node: db-server-01
│   └── 3 alert channels configured
├── Sub-Workspace B (Customer B)
│   ├── node: proxy-edge-1
│   └── 1 alert channel configured
└── Sub-Workspace C (Customer C)
    └── node: game-server-01

Each sub-workspace is fully isolated. Nodes, incidents, alert channels, users, and detection thresholds are scoped to the sub-workspace. Customers can only see their own data.

DNS Setup

Two CNAME records are needed to run a fully branded partner deployment. One serves the dashboard UI, the other handles agent reporting and REST API calls.

Record	Host	Points To	Purpose
Dashboard	`dashboard.yourcompany.com`	`whitelabel.flowtriq.com`	Branded dashboard for your customers
API	`api.yourcompany.com`	`api.flowtriq.com`	Agent reporting + REST API

The API CNAME makes the entire REST API available at https://api.yourcompany.com/api/v1/.... Same endpoints, same authentication, fully scoped to your workspace. Agents report to your API domain so customers never see Flowtriq infrastructure.

Cloudflare users: Set both CNAME records to DNS only (gray cloud), or set SSL/TLS mode to "Flexible" if you want to use the Cloudflare proxy (orange cloud).

Deploying ftagent Under Your Brand

Follow these steps to provision a customer, deploy the agent to their server, and have traffic data flow into your branded dashboard.

Step 1: Set your custom API domain

Go to Settings → White Label → API Domain and enter your API subdomain (e.g. api.yourcompany.com).

Step 2: Verify DNS

Ensure your api.yourcompany.com CNAME points to api.flowtriq.com and has propagated. Click Verify DNS in the dashboard.

Step 3: Create a sub-workspace for the customer

POST/api/v1/workspaces

# Create a sub-workspace
curl -X POST https://api.yourcompany.com/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp"
  }'

// Response 201
{
  "ok": true,
  "workspace": {
    "uuid": "ws-a1b2c3d4-...",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "created_at": "2026-07-14T12:00:00Z"
  }
}

Step 4: Create a node in that sub-workspace

POST/api/v1/workspaces/{ws-uuid}/nodes

# Add a node to the customer's sub-workspace
curl -X POST https://api.yourcompany.com/api/v1/workspaces/ws-a1b2c3d4-.../nodes \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-server-01",
    "hostname": "web01.acme.com"
  }'

// Response 201
{
  "ok": true,
  "node": {
    "uuid": "nd-e5f6a7b8-...",
    "name": "web-server-01",
    "api_key": "ft_live_abc123..."
  }
}

Important: The api_key is returned once in the create response. Store it securely. You will need it to register the agent on the customer's server.

Step 5: Install ftagent on the customer's server

# Install the agent
pip install ftagent --break-system-packages

# Register with your branded API domain
ftagent register \
  --api-url https://api.yourcompany.com \
  --api-key ft_live_abc123... \
  --node-uuid nd-e5f6a7b8-...

# Enable and start the service
systemctl enable ftagent && systemctl start ftagent

The agent will report heartbeats, metrics, and incidents to api.yourcompany.com. The customer never sees Flowtriq infrastructure.

Step 6: Use the branded deploy script (optional)

Instead of manual installation, you can generate a ready-to-run deploy script with your brand name and API domain pre-filled:

POST/api/dash/whitelabel.php?action=generate_deploy_script

This returns a bash script that your customer can run with a single command. The script handles pip installation, agent registration, and systemd setup automatically.

API Provisioning

Key endpoints for partner operations. All endpoints work through your custom API domain (https://api.yourcompany.com) or https://api.flowtriq.com.

Workspace Management

GET/api/v1/workspaces

List all sub-workspaces under your partner account.

POST/api/v1/workspaces

Create a new sub-workspace for a customer.

GET/api/v1/workspaces/{uuid}

Get details for a specific sub-workspace.

DELETE/api/v1/workspaces/{uuid}

Deactivate a sub-workspace. Nodes stop reporting, data is retained for 30 days.

Node Management (scoped to sub-workspace)

GET/api/v1/workspaces/{uuid}/nodes

List all nodes in a sub-workspace.

POST/api/v1/workspaces/{uuid}/nodes

Create a node in a sub-workspace. Returns api_key and node_uuid.

PATCH/api/v1/workspaces/{uuid}/nodes/{node}

Update a node's properties (name, location, priority, etc.).

DELETE/api/v1/workspaces/{uuid}/nodes/{node}

Delete a node from a sub-workspace.

Incidents & Partner Overview

GET/api/v1/workspaces/{uuid}/incidents

List incidents for a specific sub-workspace.

GET/api/v1/partner/overview

Aggregate stats across all sub-workspaces: total nodes, active incidents, traffic volume, and per-workspace summaries.

Full provisioning example

Create a workspace and add a node in two API calls:

# 1. Create the sub-workspace
curl -s -X POST https://api.yourcompany.com/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "slug": "acme-corp"}'

# 2. Create a node in the new workspace (use the uuid from step 1)
curl -s -X POST https://api.yourcompany.com/api/v1/workspaces/ws-a1b2c3d4-.../nodes \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "web-server-01", "hostname": "web01.acme.com"}'

# Response includes api_key and node_uuid for the agent

All standard API endpoints (nodes, incidents, channels, mitigation, allowlist, runbooks, PCAPs, scrubbing) also work through your custom domain. Refer to the Full API Reference for the complete endpoint list.

How Alerts Flow

Understanding the alert pipeline helps you configure notifications for your customers and integrate with your own monitoring stack.

Detection: ftagent detects an anomaly on the customer's server (threshold breach, protocol anomaly, or IOC match).
Report: The agent sends the incident to api.yourcompany.com/api/v1/agent/incidents.
Classification: The detection engine classifies the attack type, assigns severity, and creates an incident record.
Sub-workspace notifications: All alert channels configured in the customer's sub-workspace fire (Discord, Slack, email, webhooks, PagerDuty, etc.).
Cross-workspace webhook: If you have a cross-workspace webhook configured, your parent workspace also receives the event as an HMAC-signed POST to your endpoint.

Cross-workspace webhook payload

When a cross-workspace webhook is configured, your parent workspace receives a POST for every incident event across all sub-workspaces:

// POST to your webhook endpoint
// Content-Type: application/json
// X-Flowtriq-Signature: sha256=abc123...

{
  "event": "incident.started",
  "timestamp": "2026-07-14T15:30:00Z",
  "tenant_id": "sub-workspace-uuid",
  "data": {
    "incident_uuid": "d4e5f6a7-b8c9-...",
    "node_name": "web-server-01",
    "attack_type": "UDP Flood",
    "peak_pps": 150000,
    "severity": "high"
  }
}

Signature verification

Verify the HMAC-SHA256 signature to ensure the webhook is authentic:

import hmac, hashlib

signature = request.headers['X-Flowtriq-Signature'].replace('sha256=', '')
expected = hmac.new(
    webhook_secret.encode(),
    request.body,
    hashlib.sha256
).hexdigest()
assert hmac.compare_digest(signature, expected)

Threshold Templates

Partners can create detection threshold presets and apply them across multiple sub-workspaces. This standardizes detection settings across your entire customer base.

Create a template: Define PPS/BPS thresholds, protocol sensitivity, and detection modes via the white-label API.
Apply to a sub-workspace: Push the template to all nodes in a sub-workspace with a single API call. Existing per-node overrides are preserved unless you force-apply.
Update across customers: When you update a template, re-apply it to propagate changes to all sub-workspaces that use it.

# Create a threshold template
curl -X POST https://api.yourcompany.com/api/v1/partner/threshold-templates \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard Web Server",
    "pps_threshold": 50000,
    "bps_threshold": 500000000,
    "dynamic_baseline": true,
    "sensitivity": "medium"
  }'

# Apply template to all nodes in a sub-workspace
curl -X POST https://api.yourcompany.com/api/v1/partner/threshold-templates/tpl-uuid/apply \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspace_uuid": "ws-a1b2c3d4-..."}'

Authentication & Scoping

Partner API tokens are created in Settings → White Label → API Tokens. These tokens have elevated permissions for managing sub-workspaces.

Token scoping

You can restrict tokens to specific resources and operations. Available scopes:

Scope	Access
workspaces	Create, read, update, and deactivate sub-workspaces
nodes:read	List and view nodes across sub-workspaces
nodes:write	Create, update, and delete nodes
incidents:read	List and view incidents across sub-workspaces
channels:write	Manage alert channels in sub-workspaces
partner:overview	Access aggregate partner stats
templates:write	Create and apply threshold templates

Domain binding

Requests made through your custom API domain (api.yourcompany.com) are automatically restricted to your tenant's tokens. A token from a different workspace cannot authenticate against your domain.

Rate limits

Default	1,000 requests per minute
Burst	Up to 50 requests per second
Custom limits	Available on request for high-volume partners

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.