API Reference - FluxGate

Open-source API gateway for microservices

GET /v2/routes HTTP/1.1
Host: api.fluxgate.io
X-Fluxgate-Key: sk_live_8f9a2c1b4d7e
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...

View Authentication Download OpenAPI Spec

Security & Access

Authentication

All Admin API requests require a valid API key scoped to your FluxGate organization. Keys are generated in the dashboard under Settings → API Access and enforce strict IP allowlisting by default.

FluxGate uses HMAC-SHA256 signature validation for write operations. Include your key in the X-Fluxgate-Key header. Read-only endpoints accept Bearer tokens issued via OAuth2 client credentials flow (Client ID: fg_admin_sdk, Token URL: https://auth.fluxgate.io/oauth/token). Tokens expire after 3600 seconds and require rotation via the POST /v2/auth/rotate endpoint.

API Keys

Static keys for server-to-server communication. Rotate every 90 days. Prefix sk_live_ for production, sk_test_ for staging. Maximum 5 active keys per organization.

Service Accounts

Role-based tokens for CI/CD pipelines. Supports RBAC scopes: routes:write, plugins:read, configs:admin. Bind to specific Kubernetes namespaces using the namespace claim.

Resource Management

Endpoints List

Programmatic control over routing rules, plugin chains, and global gateway configurations. All endpoints return JSON, support pagination via cursor-based after parameters, and enforce strict rate limits (120 req/min for reads, 30 req/min for writes).

Routes

GET /v2/routes — List all active routing rules with upstream health status

POST /v2/routes — Create a new path, host, or header-based route

PATCH /v2/routes/{id} — Update timeout, retries, circuit breaker thresholds, or upstream targets

Plugins

GET /v2/plugins — Retrieve installed middleware stack and execution order

PUT /v2/plugins/{id}/config — Modify rate-limiting, JWT validation, or request transformation rules

Gateway Config

GET /v2/config/global — Fetch current TLS, CORS, and structured logging settings

POST /v2/config/validate — Dry-run configuration changes before cluster-wide deployment

Usage Patterns

Request & Response Examples

Below are concrete curl commands demonstrating typical Admin API workflows. Replace placeholder credentials with your organization's keys. All payloads must be UTF-8 encoded JSON.

# Create a new route with JWT validation plugin
curl -X POST https://api.fluxgate.io/v2/routes \
  --header "Content-Type: application/json" \
  --header "X-Fluxgate-Key: sk_live_8f9a2c1b4d7e" \
  --data '{
    "name": "payments-service-v2",
    "match": {"path": "/api/v2/payments/*", "methods": ["POST", "GET"]},
    "upstream": "https://pay.internal.mesh:8443",
    "plugins": [{"id": "jwt_auth", "config": {"issuer": "https://auth.acme.com"}}]
  }'

Response (201 Created):

{
  "id": "rt_9x4m2p1q",
  "status": "active",
  "created_at": "2024-11-14T09:23:11Z",
  "sync_status": "propagated_to_all_nodes"
}

Response (403 Forbidden - Insufficient Scope):

{
  "error": "scope_mismatch",
  "message": "Token lacks routes:write permission. Contact org admin to elevate service account.",
  "request_id": "req_77f2a9c1"
}