Skip to main content

Connect a Third-Party Gateway with stoa-connect

stoa-connect is a lightweight Go agent that runs alongside your existing API gateway (Kong, Gravitee, or webMethods) and connects it to the STOA Control Plane — no gateway replacement required.

What You'll Accomplish​

By the end of this guide, your third-party gateway will:

  • Appear in the STOA Console under Gateways
  • Expose its APIs in the Control Plane inventory (auto-discovered every 60 seconds)
  • Receive policies pushed from STOA automatically
  • Send heartbeats every 30 seconds so the Console shows live health

Architecture​

VPS / On-Premise
┌─────────────────────────────────────────┐
│  Third-Party Gateway (Kong/Gravitee/wM) │
│  ← admin API ─────────────────────┐     │
│                                    │     │
│  stoa-connect agent ──────────────┘     │
│  (Go binary, port 8090)                 │
│     ├── register with CP                │
│     ├── heartbeat 30s                   │
│     ├── discover APIs 60s               │
│     └── sync policies 60s              │
└──────────────────┬──────────────────────┘
                   │ HTTPS (X-Gateway-Key)
                   ▼
         STOA Control Plane
         (${STOA_API_URL})

Prerequisites​

  • A running Kong, Gravitee, or webMethods gateway with its admin API accessible locally
  • A STOA account at console.gostoa.dev
  • A Gateway API Key from the STOA Console (Settings → Gateways → New Key)

Step 1 — Install stoa-connect​

curl -sSL https://get.gostoa.dev/connect | sh

Verify the installation:

stoa-connect --version

Step 2 — Configure​

Create a .env file (or export the variables into your shell / systemd unit):

# Control Plane connection
export STOA_CONTROL_PLANE_URL="${STOA_API_URL}"
export STOA_GATEWAY_API_KEY="gw_your_key_here"
export STOA_INSTANCE_NAME="kong-prod-01"    # auto-detected from hostname if omitted
export STOA_ENVIRONMENT="production"

# Gateway admin API
export STOA_GATEWAY_TYPE="kong"
export STOA_GATEWAY_ADMIN_URL="http://localhost:8001"
export STOA_GATEWAY_ADMIN_TOKEN="your-kong-admin-token"
VariableRequiredDefaultDescription
STOA_CONTROL_PLANE_URLYes—Control Plane API base URL
STOA_GATEWAY_API_KEYYes—X-Gateway-Key for CP authentication
STOA_GATEWAY_TYPEYesautokong, gravitee, or webmethods
STOA_GATEWAY_ADMIN_URLYes—Local gateway admin API URL
STOA_INSTANCE_NAMENohostnameIdentifier shown in the Console
STOA_ENVIRONMENTNoproductionEnvironment label
STOA_HEARTBEAT_INTERVALNo30sHeartbeat frequency
STOA_CONNECT_PORTNo8090Local HTTP port for the agent

Step 3 — Run​

stoa-connect

On startup, stoa-connect will:

  1. Register the gateway with the Control Plane (POST /v1/internal/gateways/register)
  2. Discover APIs from the local gateway admin API
  3. Start the heartbeat loop (every 30 seconds)
  4. Begin policy sync (every 60 seconds)

Step 4 — Verify​

Check the agent is healthy:

# Check agent health (replace URL with your agent's address)
curl -s http://localhost:8090/health | jq

Expected output:

{
  "status": "ok",
  "version": "0.3.0",
  "gateway_id": "a1b2c3d4-...",
  "discovered_apis": 12
}

Or use the CLI:

stoactl connect status --url http://localhost:8090

Confirm the gateway appears in the Console at console.gostoa.dev under Gateways. The status indicator should be green within 30 seconds.

CLI Reference​

stoactl connect provides three subcommands for day-to-day operations:

# Show agent status and connectivity
stoactl connect status --url http://localhost:8090

# Trigger an immediate API discovery (instead of waiting 60s)
stoactl connect discover --admin-url http://localhost:8001

# Force a policy sync from the Control Plane
stoactl connect sync --url http://localhost:8090

Troubleshooting​

SymptomLikely CauseFix
UNAUTHORIZED on startupInvalid or expired STOA_GATEWAY_API_KEYRegenerate the key in Console → Settings → Gateways
Gateway stays OFFLINE in ConsoleHeartbeat not reaching CPCheck firewall rules allow outbound HTTPS to ${STOA_API_URL}
0 APIs discoveredWrong STOA_GATEWAY_ADMIN_URLVerify with curl ${STOA_GATEWAY_ADMIN_URL}/health
Policy sync failsAdmin credentials rejectedCheck STOA_GATEWAY_ADMIN_TOKEN / USER / PASSWORD

For structured logs, set LOG_LEVEL=debug before starting the agent.

Companion versus stoa-connect​

stoa-connect is the GitOps path for a third-party gateway. It syncs desired state to the gateway admin API (webMethods, Kong, Gravitee, and Envoy adapters in the stoa repository) and stays off the client request path.

The companion is a different integration. The same Rust binary, with STOA_GATEWAY_MODE=sidecar, answers POST /authz for a host in the same pod or for an application callout. The host keeps authentication, routing, and enforcement. That path is not a recorded live Kong or webMethods demo. Mesh adapters are design notes. See Companion usage.

Next Steps​

  • Multi-Gateway Setup — manage multiple gateways from a single Control Plane (coming soon)
  • Gateway Auto-Registration — native STOA gateway registration without an agent (coming soon)
  • OPA Policies — write policies that stoa-connect will sync to your gateway (coming soon)