Connection

Field	Type	Behavior	Description
name	string	OUTPUT_ONLY	Resource name (connections/{id})
connection_type	ConnectionType	REQUIRED	Type of external system (e.g. CONNECTION_TYPE_POSTGRES, CONNECTION_TYPE_SLACK)
display_name	string	REQUIRED	Human-readable name for the connection
description	string	REQUIRED	Description of what this connection provides
create_time	timestamp	OUTPUT_ONLY	When the connection was created
update_time	timestamp	OUTPUT_ONLY	When the connection was last modified
delete_time	timestamp	OUTPUT_ONLY	When the connection was soft-deleted (null if active)
secret_id	string		ID of the secret storing full connection details
connection_details	ConnectionDetails	REQUIRED	Connection-specific configuration
tool_configurations	ToolConfiguration[]		Which tools are enabled for this connection
read_only	boolean	OUTPUT_ONLY	Whether the connection is system-managed and cannot be edited
shell_environment	ShellEnvironment	OUTPUT_ONLY	Shell prompt information (populated on Get only)
connection_status	Status	OUTPUT_ONLY	Operational status of credential resolution (nil or OK means healthy)

Example

{
  "name": "connections/prod-iceberg",
  "connectionType": "CONNECTION_TYPE_ICEBERG",
  "displayName": "Production Iceberg",
  "description": "Iceberg connection for production data lake",
  "createTime": "2026-02-07T08:28:56.588670Z",
  "updateTime": "2026-02-07T08:28:56.588670Z",
  "secretId": "conn_778f2937dc19466086069ee42d234b0a"
}

Connection Type

Value	Description
CONNECTION_TYPE_POSTGRES	PostgreSQL database
CONNECTION_TYPE_HTTP	Generic HTTP API
CONNECTION_TYPE_GOOGLE_POSTMASTER	Google Postmaster Tools
CONNECTION_TYPE_PYLON	Pylon customer support platform
CONNECTION_TYPE_GITHUB	GitHub App installation
CONNECTION_TYPE_SLACK	Slack workspace
CONNECTION_TYPE_PROMQL	PromQL-compatible Prometheus API
CONNECTION_TYPE_LINEAR	Linear project management
CONNECTION_TYPE_AWS	AWS (IAM role assumption or static credentials)
CONNECTION_TYPE_GCP	GCP (service account authentication)
CONNECTION_TYPE_CLICKHOUSE	ClickHouse database
CONNECTION_TYPE_MYSQL	MySQL database
CONNECTION_TYPE_ICEBERG	Apache Iceberg REST catalog
CONNECTION_TYPE_DATADOG	Datadog observability platform
CONNECTION_TYPE_INCIDENT_IO	incident.io webhook integration
CONNECTION_TYPE_PAGERDUTY	PagerDuty incident management
CONNECTION_TYPE_OPENAPI	OpenAPI-described REST API
CONNECTION_TYPE_CLERK	Clerk user management and authentication
CONNECTION_TYPE_VANTA	Vanta compliance and security automation
CONNECTION_TYPE_CONVEX	Convex log stream webhook integration
CONNECTION_TYPE_WORKOS	WorkOS user management, SSO, and directory sync
CONNECTION_TYPE_TRINO	Trino distributed SQL query engine
CONNECTION_TYPE_EMAIL_WEBHOOK	Guarded customer-email delivery to a fixed webhook endpoint
CONNECTION_TYPE_GRPC	gRPC or ConnectRPC service via server reflection
CONNECTION_TYPE_CURSOR	Cursor AI code editor — trigger cloud agents to fix issues
CONNECTION_TYPE_ELASTICSEARCH	Elasticsearch cluster (queried via Elasticsearch SQL)

Tool

Each connection type supports a set of tools that agents can use. The enabled_tools field on AgentConnection and RunbookConnection references values from this enum.

Value	Description
TOOL_POSTGRES_QUERY	Execute a read-only SQL query against PostgreSQL
TOOL_POSTGRES_WRITE_QUERY	Execute a read-write SQL query against PostgreSQL
TOOL_HTTP_REQUEST	Make an HTTP request
TOOL_GITHUB_SEARCH_CODE	Search code in GitHub repositories
TOOL_GITHUB_GET_FILE	Get file contents from a GitHub repository
TOOL_GITHUB_LIST_DIRECTORY	List files in a GitHub repository directory
TOOL_GITHUB_GET_PR	Get a GitHub pull request
TOOL_GITHUB_GET_ISSUE	Get a GitHub issue
TOOL_GITHUB_PULL_REQUEST_SEARCH	Search GitHub pull requests
TOOL_GITHUB_CREATE_ISSUE	Create a GitHub issue
TOOL_GITHUB_ADD_ISSUE_COMMENT	Add a comment to a GitHub issue
TOOL_GITHUB_LIST_ISSUES	List GitHub issues
TOOL_GITHUB_CREATE_PR_COMMENT	Add a comment to a GitHub pull request
TOOL_GITHUB_LIST_PR_COMMENTS	List comments on a GitHub pull request
TOOL_GITHUB_LIST_PR_REVIEWS	List reviews on a GitHub pull request
TOOL_GITHUB_LIST_ORGANIZATION_MEMBERS	List members of a GitHub organization
TOOL_GITHUB_LIST_REPOS	List repositories in a GitHub organization
TOOL_PROMQL_QUERY	Execute an instant PromQL query
TOOL_PROMQL_QUERY_RANGE	Execute a range PromQL query
TOOL_PROMQL_LABELS	List all label names from Prometheus
TOOL_PROMQL_LABEL_VALUES	Get label values from Prometheus
TOOL_PROMQL_SERIES	Get time series from Prometheus
TOOL_PROMQL_METADATA	Get metric metadata from Prometheus
TOOL_GOOGLE_POSTMASTER_LIST_DOMAINS	List domains in Google Postmaster Tools
TOOL_GOOGLE_POSTMASTER_GET_TRAFFIC_STATS	Get traffic stats from Google Postmaster Tools
TOOL_PYLON_LIST_ISSUES	List issues from Pylon
TOOL_SLACK_SEND_MESSAGE	Send a message in Slack
TOOL_FIRETIGER_QUERY	Query Firetiger’s data lake
TOOL_FIRETIGER_CODEBASE_SEARCH	Search code across configured repositories
TOOL_LINEAR_LIST_ISSUES	List issues from Linear
TOOL_LINEAR_LIST_USERS	List users from Linear
TOOL_CLICKHOUSE_QUERY	Execute a query against ClickHouse
TOOL_MYSQL_QUERY	Execute a read-only query against MySQL
TOOL_ICEBERG_QUERY	Query an Apache Iceberg table
TOOL_DATADOG_QUERY_METRICS	Query metrics from Datadog
TOOL_DATADOG_QUERY_LOGS	Query logs from Datadog
TOOL_OPENAPI_REQUEST	Make HTTP requests to an OpenAPI-described API
TOOL_OPENAPI_SCHEMA	Introspect the OpenAPI spec for available endpoints and schemas
TOOL_GCP_QUERY_METRICS	Query GCP Cloud Monitoring metrics via PromQL
TOOL_TRINO_QUERY	Execute a query against a Trino cluster
TOOL_EMAIL_WEBHOOK_SEND	Send an approved customer email via a guarded webhook
TOOL_GRPC_SERVICES	List all services and methods available via gRPC server reflection
TOOL_GRPC_DESCRIBE	Show the full schema of a gRPC service including field types and documentation
TOOL_GRPC_REQUEST	Invoke a gRPC or ConnectRPC method with a JSON payload

Tool Configuration

Controls whether a specific tool is enabled on a connection.

Field	Type	Description
tool	Tool	The tool being configured
is_enabled	boolean	Whether this tool is enabled

Connection Details

Connection-specific configuration. This is a union type – exactly one variant is set, matching the connection’s connection_type. The fields vary by connection type (e.g. host/port/database for PostgreSQL, base URL and headers for HTTP). Refer to the connection creation UI or ftops api connections for the fields available for each type.

HTTP Connection Details

Field	Type	Description
base_url	string	Base URL for HTTP requests
allowed_routes	string[]	Allowed route patterns
headers	map<string, string>	Non-auth headers included in every request (e.g. Content-Type, X-Tenant-ID)
max_response_size_bytes	uint64	Maximum response size in bytes
timeout_seconds	uint32	Request timeout in seconds
oauth_client_credentials	OAuthClientCredentials	OAuth 2.0 Client Credentials grant (oneof auth)
bearer_token	HttpBearerAuth	Static Bearer token (oneof auth)
basic_auth	HttpBasicAuth	HTTP Basic authentication (oneof auth)
static_headers	HttpAuthStaticHeaders	Auth via raw headers (oneof auth)
webhook_signing_secret	string	Optional outbound webhook signing secret

Authentication is configured via the auth oneof — set exactly one of the four auth fields above.

OAuth Client Credentials

The resolver 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.

Field	Type	Behavior	Description
token_url	string	REQUIRED	Token endpoint URL (must use HTTPS, e.g. https://api.vanta.com/oauth/token)
client_id	string		OAuth client ID (returned in responses)
client_secret	string	INPUT_ONLY	OAuth client secret (not returned in responses)
scopes	string		Optional space-separated scopes to request
extra_params	map<string, string>		Optional additional form parameters for the token request (e.g. audience)
access_token	string	OUTPUT_ONLY	Current access token (populated by the resolver)
token_expires_at	timestamp	OUTPUT_ONLY	When the current access token expires

Bearer Token

Field	Type	Behavior	Description
token	string	INPUT_ONLY	Bearer token value

Basic Auth

Field	Type	Behavior	Description
username	string		Username
password	string	INPUT_ONLY	Password

Static Headers

Field	Type	Behavior	Description
headers	map<string, string>	INPUT_ONLY	Auth headers to include in every request

Non-auth headers can be used alongside any auth method (e.g. X-Tenant-ID). Auth headers are resolved from the auth field and merged into the request; do not duplicate auth headers in headers.

AWS SigV4 Auth

AWS Signature Version 4 authentication for services that require SigV4-signed requests (e.g., Amazon Managed Prometheus). The server resolves the configured credentials into temporary session credentials before each request.

Field	Type	Behavior	Description
region	string	REQUIRED	AWS region for SigV4 signing (e.g. us-west-2)
assume_role	AwsAssumeRoleAuth		IAM role assumption (oneof credentials)
static_credentials	AwsStaticCredentialsAuth		Static IAM credentials (oneof credentials)
session_credentials	AwsSessionCredentials	OUTPUT_ONLY	Resolved temporary credentials (populated by the server)

Exactly one of assume_role or static_credentials must be set.

AWS Assume Role Auth

Field	Type	Behavior	Description
role_arn	string	REQUIRED	ARN of the IAM role to assume (e.g. arn:aws:iam::123456789012:role/prometheus-read)
external_id	string		Optional external ID for cross-account access

AWS Static Credentials Auth

Field	Type	Behavior	Description
access_key_id	string	INPUT_ONLY, REQUIRED	AWS access key ID
secret_access_key	string	INPUT_ONLY, REQUIRED	AWS secret access key
session_token	string	INPUT_ONLY	Optional session token for temporary credentials

HTTP Webhook Signing

When webhook_signing_secret is present, outbound HTTP requests can include a GitHub-style X-Webhook-Signature header computed as sha256=<hex digest> over the exact raw request body bytes. The runtime only signs POST, PUT, DELETE, and PATCH requests, and only when a request body is actually sent.

Email Webhook Connection Details

Guarded customer-email delivery to a fixed webhook endpoint.

Field	Type	Description
base_url	string	Full webhook URL for customer email delivery
allowed_routes	string[]	Allowed route patterns. In practice this is fixed to POST /
headers	map<string, string>	Non-auth headers included in every request
max_response_size_bytes	uint64	Maximum response size in bytes
timeout_seconds	uint32	Request timeout in seconds
oauth_client_credentials	OAuthClientCredentials	OAuth 2.0 Client Credentials grant (oneof auth)
bearer_token	HttpBearerAuth	Static Bearer token (oneof auth)
basic_auth	HttpBasicAuth	HTTP Basic authentication (oneof auth)
static_headers	HttpAuthStaticHeaders	Auth via raw headers (oneof auth)
webhook_signing_secret	string	Optional outbound webhook signing secret
slack_connection_name	string	Optional Slack connection to notify when a customer email is waiting for review
slack_channel	string	Optional Slack channel to notify when a customer email is waiting for review

Authentication is configured via the auth oneof — set exactly one of the four auth fields above. The auth field shapes are the same as HTTP Connection Details.

If both slack_connection_name and slack_channel are set, Firetiger sends a best-effort Slack notification when a customer email is waiting for review. If they are omitted, the guarded email flow still works normally.

gRPC Connection Details

Connect to a gRPC or ConnectRPC service. Agents use the grpc_services, grpc_describe, and grpc_request tools for reflection-based discovery and method invocation.

Field	Type	Behavior	Description
address	string	REQUIRED	Server address in host:port format (e.g. api.example.com:443)
protocol	enum		Wire protocol for method invocation. One of GRPC_PROTOCOL_GRPC (default), GRPC_PROTOCOL_CONNECT, GRPC_PROTOCOL_GRPCWEB. Service discovery always uses gRPC regardless of this setting.
basic_auth	BasicAuth		HTTP Basic authentication (oneof auth)
bearer_auth	BearerAuth		Bearer token authentication (oneof auth)

Authentication is optional — omit the auth field for unauthenticated services. When auth is configured, credentials are injected as HTTP headers on TLS connections. Auth injection requires port 443; credentials will not be injected for non-standard ports.

gRPC Basic Auth

Field	Type	Behavior	Description
username	string		Username
password	string	INPUT_ONLY	Password

gRPC Bearer Auth

Field	Type	Behavior	Description
token	string	INPUT_ONLY	Bearer token value

PromQL Connection Details

Connect to a Prometheus-compatible metrics API. Agents use the promql_query, promql_query_range, promql_labels, promql_label_values, promql_series, and promql_metadata tools.

Field	Type	Behavior	Description
base_url	string	REQUIRED	Base URL of the Prometheus API (e.g. https://prometheus.example.com)
timeout	duration		Request timeout for API calls. Defaults to 30 seconds
basic	HttpBasicAuth		HTTP Basic authentication (oneof auth)
bearer	HttpBearerAuth		Bearer token authentication (oneof auth)
sigv4	AwsSigV4Auth		AWS SigV4 authentication for Amazon Managed Prometheus (oneof auth)

Authentication is optional — omit the auth field entirely for Prometheus instances that don’t require authentication (e.g. internal/VPN-only deployments). When auth is needed, set exactly one of the three auth fields above.

Example (no auth)

{
  "connectionType": "CONNECTION_TYPE_PROMQL",
  "displayName": "Internal Prometheus",
  "description": "VPN-only Prometheus instance",
  "connectionDetails": {
    "promql": {
      "baseUrl": "https://prometheus.internal.example.com"
    }
  }
}

Example (bearer token)

{
  "connectionType": "CONNECTION_TYPE_PROMQL",
  "displayName": "Grafana Cloud Prometheus",
  "description": "Grafana Cloud managed Prometheus",
  "connectionDetails": {
    "promql": {
      "baseUrl": "https://prometheus-prod-01-eu-west-0.grafana.net/api/prom",
      "bearer": {
        "token": "glc_..."
      }
    }
  }
}

Example (AWS SigV4 — Amazon Managed Prometheus)

{
  "connectionType": "CONNECTION_TYPE_PROMQL",
  "displayName": "Production AMP",
  "description": "Amazon Managed Prometheus workspace",
  "connectionDetails": {
    "promql": {
      "baseUrl": "https://aps-workspaces.us-west-2.amazonaws.com/workspaces/ws-abc123",
      "sigv4": {
        "region": "us-west-2",
        "assumeRole": {
          "roleArn": "arn:aws:iam::123456789012:role/prometheus-read"
        }
      }
    }
  }
}

OpenAPI Connection Details

Connect to any REST API that publishes an OpenAPI (Swagger) specification. The agent can introspect the spec to discover endpoints and make authenticated requests.

Field	Type	Description
spec_url	string	URL to fetch the OpenAPI specification (JSON or YAML)
server_url	string	Base URL of the API server. If empty, derived from the spec’s servers[0].url
oauth_client_credentials	OAuthClientCredentials	OAuth 2.0 Client Credentials grant (oneof auth)
bearer_token	HttpBearerAuth	Static Bearer token (oneof auth)
basic_auth	HttpBasicAuth	HTTP Basic authentication (oneof auth)

Authentication is configured via the auth oneof — set exactly one of the three auth fields above. The auth types reuse the same messages as HTTP Connection Details.

When server_url is omitted, the resolver fetches the spec and extracts the base URL from servers[0].url, resolving relative paths (e.g. /v1) against the spec URL.

Example

{
  "connectionType": "CONNECTION_TYPE_OPENAPI",
  "displayName": "Vanta API",
  "description": "Vanta compliance platform API",
  "connectionDetails": {
    "openapi": {
      "specUrl": "https://firetiger-public.s3.us-west-2.amazonaws.com/connections/vanta/openapi.json",
      "serverUrl": "https://api.vanta.com/v1",
      "oauthClientCredentials": {
        "tokenUrl": "https://api.vanta.com/oauth/token",
        "clientId": "my-client-id",
        "clientSecret": "my-client-secret",
        "scopes": "vanta-api.all:read"
      }
    }
  }
}

Clerk Connection Details

Connect to the Clerk Backend API for user management and authentication. Uses a Bearer token (Clerk secret key) for auth.

Field	Type	Description
bearer_token	HttpBearerAuth	Clerk Secret Key (sk_live_... or sk_test_...) as Bearer token (oneof auth)

Authentication is configured via the auth oneof. The Clerk connection automatically configures the OpenAPI spec URL (https://clerk.com/docs/reference/spec/bapi/2025-11-10) and server URL (https://api.clerk.com). Agents use the openapi_schema and openapi_request tools to interact with the API.

Example

{
  "connectionType": "CONNECTION_TYPE_CLERK",
  "displayName": "Clerk",
  "description": "Clerk user management and authentication API",
  "connectionDetails": {
    "clerk": {
      "bearerToken": {
        "token": "sk_live_..."
      }
    }
  }
}

Vanta Connection Details

Connect to the Vanta API for compliance and security automation. Uses OAuth 2.0 Client Credentials for authentication.

Field	Type	Description
oauth_client_credentials	OAuthClientCredentials	OAuth 2.0 Client Credentials for Vanta API (oneof auth)

Authentication is configured via the auth oneof. The Vanta connection automatically configures the OpenAPI spec URL (https://firetiger-public.s3.us-west-2.amazonaws.com/connections/vanta/openapi.json) and server URL (https://api.vanta.com/v1). Agents use the openapi_schema and openapi_request tools to interact with the API.

Example

{
  "connectionType": "CONNECTION_TYPE_VANTA",
  "displayName": "Vanta",
  "description": "Vanta compliance and security automation API",
  "connectionDetails": {
    "vanta": {
      "oauthClientCredentials": {
        "tokenUrl": "https://api.vanta.com/oauth/token",
        "clientId": "my-client-id",
        "clientSecret": "my-client-secret",
        "scopes": "vanta-api.all:read"
      }
    }
  }
}

WorkOS Connection Details

Connect to the WorkOS API for user management, SSO, directory sync, and audit logs. Uses standard WorkOS API authentication (API key starting with sk_). Agents use the openapi_schema and openapi_request tools to interact with the API.

Field	Type	Description
bearer_token	HttpBearerAuth	WorkOS API key as Bearer token (oneof auth)
read_only	boolean	When true, only GET requests are allowed

Example

{
  "connectionType": "CONNECTION_TYPE_WORKOS",
  "displayName": "WorkOS",
  "connectionDetails": {
    "workOs": {
      "bearerToken": { "token": "sk_..." },
      "readOnly": true
    }
  }
}

Trino Connection Details

Connect to a Trino distributed SQL query engine (including Starburst). Agents use the query_trino tool to execute SQL queries.

Field	Type	Behavior	Description
host	string	REQUIRED	Trino coordinator host (e.g. trino.example.com)
port	int32	REQUIRED	Coordinator port (default 8080 for HTTP, 443 for HTTPS)
catalog	string	REQUIRED	Default catalog (e.g. hive, iceberg, tpch)
schema	string		Default schema within the catalog (optional)
username	string	REQUIRED	Username for authentication
password	string	INPUT_ONLY	Password (optional — Trino supports no-auth setups)
secure	boolean		Enable HTTPS (default true)

Example

{
  "connectionType": "CONNECTION_TYPE_TRINO",
  "displayName": "Starburst Trino",
  "description": "Production Trino cluster",
  "connectionDetails": {
    "trino": {
      "host": "trino.example.com",
      "port": 443,
      "catalog": "hive",
      "schema": "default",
      "username": "trino_user",
      "password": "secret",
      "secure": true
    }
  }
}

Elasticsearch Connection Details

Connect to an Elasticsearch cluster. Agents drive Elasticsearch queries through the shell environment — $ES_URL is exported and an Authorization header (Basic or ApiKey, based on the selected auth branch) is injected by the fireshell proxy. Use Elasticsearch SQL via POST $ES_URL/_sql?format=json. There is no dedicated TOOL_* enum for Elasticsearch.

Field	Type	Behavior	Description
url	string	REQUIRED	Cluster base URL including scheme (e.g. https://es.example.com:9200)
auth	oneof	REQUIRED	Authentication method. Set exactly one of basic, api_key, or none
auth.basic.username	string	REQUIRED (within basic)	Username for HTTP Basic auth
auth.basic.password	string	INPUT_ONLY	Password for HTTP Basic auth
auth.api_key.token	string	INPUT_ONLY	Base64-encoded Elastic API key, sent as Authorization: ApiKey <token> (the api_key oneof branch wraps an HttpBearerAuth-shaped message; only the header scheme prefix differs from a standard bearer token)
auth.none	message		Explicitly unauthenticated. For local/dev clusters with security disabled.
tls_skip_verify	boolean		Skip TLS certificate verification. Use only for self-signed clusters on trusted networks.

When updating a connection, omit auth.basic.password or auth.api_key.token to keep the existing credential.

Example

{
  "connectionType": "CONNECTION_TYPE_ELASTICSEARCH",
  "displayName": "Production Elasticsearch",
  "description": "Primary search cluster",
  "connectionDetails": {
    "elasticsearch": {
      "url": "https://es.example.com:9200",
      "basic": {
        "username": "elastic",
        "password": "secret"
      }
    }
  }
}

Datadog Connection Details

Connect to Datadog for querying metrics, logs, traces, monitors, and dashboards. Both an API key and an Application Key are required.

Field	Type	Behavior	Description
site	string	REQUIRED	Datadog site (e.g. datadoghq.com, datadoghq.eu, us3.datadoghq.com)
api_key	string	INPUT_ONLY	Datadog API key. Required for all Datadog API requests. Find it in Organization Settings → API Keys.
application_key	string	INPUT_ONLY	Datadog Application Key. Required for query operations (metrics, logs, traces) and management endpoints (monitors, dashboards). Find it in Organization Settings → Application Keys.

When updating a connection, omit api_key and application_key to keep the existing values.

Example

{
  "connectionType": "CONNECTION_TYPE_DATADOG",
  "displayName": "Datadog Production",
  "description": "Datadog observability platform - query metrics, search logs, inspect monitors, and analyze APM traces",
  "connectionDetails": {
    "datadog": {
      "site": "datadoghq.com",
      "apiKey": "your-api-key",
      "applicationKey": "your-application-key"
    }
  }
}

Cursor Connection Details

Connect to Cursor to trigger cloud agents that automatically fix issues in your codebase.

Field	Type	Behavior	Description
api_key	string	INPUT_ONLY	Cursor API key. Find it at cursor.com/dashboard/cloud-agents under My User API Keys.

When updating a connection, omit api_key to keep the existing value.

Example

{
  "connectionType": "CONNECTION_TYPE_CURSOR",
  "displayName": "Cursor",
  "description": "Cursor AI code editor — trigger cloud agents to fix issues",
  "connectionDetails": {
    "cursor": {
      "apiKey": "your-cursor-api-key"
    }
  }
}

Shell Environment

Shell prompt information for the connection, populated only on Get requests.

Field	Type	Description
prompt	string	Shell prompt text for interactive sessions

Status

Operational status of the connection’s credential resolution, following the google.rpc.Status format.

Field	Type	Description
code	integer	Status code (0 means OK)
message	string	Human-readable error message (empty when healthy)