HTTP Connections

HTTP connections enable agents to interact with RESTful APIs and web services.

Recommended: Create and manage connections via the web UI at https://ui.cloud.firetiger.com/settings/connections

Connection Parameters

An HTTP connection requires the following configuration:

Required Parameters

Parameter Type Description
base_url string Base URL including scheme, host, and optional base path (e.g., https://api.example.com/v1)
allowed_routes string[] List of route patterns that agents can access (see Route Patterns below)

Optional Parameters

Parameter Type Description Default
headers map<string,string> Non-auth headers to include in all requests (e.g. Content-Type, X-Tenant-ID) None
max_response_size_bytes int64 Maximum response body size in bytes 10MB (10485760)
timeout_seconds int32 Request timeout in seconds 30 seconds

Important Notes

  • HTTPS Required: The base_url must use HTTPS (not HTTP) for security. HTTP URLs will be rejected.
  • Maximum Limits:
    • max_response_size_bytes cannot exceed 10MB (10485760 bytes)
    • timeout_seconds cannot exceed 300 seconds (5 minutes)

Route Patterns

The allowed_routes parameter controls which endpoints agents can access. Uses http.ServeMux syntax.

Pattern types:

"allowed_routes": [
  "GET /api/status",           // Exact match
  "GET /api/users/",           // Prefix match (trailing slash)
  "GET /api/users/{id}",       // Wildcard (single segment)
  "GET /files/{path...}"       // Wildcard (remaining segments)
]

Supported methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

Authentication

Authentication is configured via the auth oneof — set exactly one of the following methods.

OAuth Client Credentials

Automatically obtains and refreshes an OAuth 2.0 access token using the client credentials grant. The token is injected as an Authorization: Bearer header on each request.

"oauth_client_credentials": {
  "token_url": "https://auth.example.com/oauth/token",
  "client_id": "my-client-id",
  "client_secret": "my-client-secret",
  "scopes": "api.read api.write",
  "extra_params": {
    "audience": "https://api.example.com"
  }
}

Bearer Token

A static Bearer token sent as Authorization: Bearer <token>.

"bearer_token": {
  "token": "sk-your-token"
}

Basic Auth

HTTP Basic authentication with username and password.

"basic_auth": {
  "username": "user",
  "password": "pass"
}

Static Headers

Raw auth headers included in every request. Use this when the API requires a custom auth header format.

"static_headers": {
  "headers": {
    "Authorization": "Bearer sk-your-token",
    "X-API-Key": "your-key"
  }
}

Non-auth headers (in the top-level connection details) can be used alongside any auth method for headers like Content-Type or X-Tenant-ID.

Webhook Signing

If webhook_signing_secret is configured, Firetiger signs outbound HTTP requests that include a request body and adds the signature in the X-Webhook-Signature header.

The header value uses this format:

sha256=<hex digest>

The digest is computed as HMAC-SHA256 over the exact raw HTTP request body using the configured signing secret.

Validation Steps

On your receiving service:

  1. Read the raw request body bytes exactly as received
  2. Compute HMAC-SHA256(secret, raw_body)
  3. Hex-encode the digest
  4. Compare it to the value after the sha256= prefix in X-Webhook-Signature
  5. Reject the request if the values do not match

Example Validation 

import hashlib
import hmac

secret = b"your-signing-secret"
raw_body = request_body_bytes
received = request.headers["X-Webhook-Signature"]

expected = "sha256=" + hmac.new(secret, raw_body, hashlib.sha256).hexdigest()

if not hmac.compare_digest(expected, received):
    raise ValueError("invalid webhook signature")

Important Notes

  • Use the raw request body bytes, not a re-serialized JSON object
  • Compare signatures with a constant-time comparison function when available
  • Rotate the signing secret if you suspect it has been exposed

Description Field

Document the API endpoints and usage patterns.

Example:

Databricks API for cluster management.

Endpoints:
- GET /api/2.0/clusters/list - List all clusters
- GET /api/2.0/clusters/get?cluster_id=<id> - Get cluster details
- POST /api/2.0/clusters/start - Start cluster (body: {"cluster_id": "..."})
- POST /api/2.0/clusters/terminate - Stop cluster (body: {"cluster_id": "..."})

Response format: JSON
Rate limit: 30 req/min

Example Connection 

{
  "display_name": "Databricks API",
  "description": "Databricks API for cluster management...",
  "connection_details": {
    "http": {
      "base_url": "https://api.databricks.com",
      "allowed_routes": [
        "GET /api/2.0/clusters/list",
        "GET /api/2.0/clusters/get",
        "POST /api/2.0/clusters/start"
      ],
      "bearer_token": {
        "token": "dapi123..."
      },
      "max_response_size_bytes": 5242880,
      "timeout_seconds": 30
    }
  }
}

Best Practices

  • Least privilege - Only include necessary routes in allowed_routes
  • Document endpoints - List available endpoints and response formats in description
  • Include rate limits - Document API rate limits in the description
  • HTTPS required - All connections must use HTTPS
  • Prefer OAuth - Use OAuth Client Credentials when the API supports it for automatic token refresh
  • Use webhook signing when the destination verifies HMAC signatures
This site uses Just the Docs, a documentation theme for Jekyll.