Connections

Connections are integrations with external tools and services. Each connection stores credentials and configuration for a specific external system (databases, SaaS platforms, cloud providers, etc.).

Service: firetiger.connections.v1.ConnectionsService

Resource name pattern: connections/{connection_id}

Access: Read-only

Resource type: Connection

Connections are configured through the Firetiger UI. The API provides read-only access to list and inspect your configured connections.

Example flow

List your connections to see what is available, then fetch a specific one to inspect its full configuration.

1. List connections

curl "https://api.cloud.firetiger.com/v1/connections" \
  -u "$USERNAME:$PASSWORD"

{
  "connections": [
    {
      "name": "connections/prod-postgres",
      "displayName": "Production Postgres",
      "connectionType": "CONNECTION_TYPE_POSTGRES"
    },
    {
      "name": "connections/staging-http",
      "displayName": "Staging API",
      "connectionType": "CONNECTION_TYPE_HTTP"
    }
  ]
}

2. Get a specific connection

Use the resource name from the list response to fetch full details, including resolved credentials and tool configurations.

curl "https://api.cloud.firetiger.com/v1/connections/prod-postgres" \
  -u "$USERNAME:$PASSWORD"

{
  "connection": {
    "name": "connections/prod-postgres",
    "displayName": "Production Postgres",
    "description": "Primary production database",
    "connectionType": "CONNECTION_TYPE_POSTGRES",
    "connectionDetails": {
      "postgres": {
        "host": "db.example.com",
        "port": 5432,
        "database": "production",
        "username": "readonly",
        "password": "resolved-secret",
        "sslMode": "require"
      }
    },
    "toolConfigurations": [
      {
        "tool": "TOOL_POSTGRES_QUERY",
        "enabled": true
      }
    ]
  }
}

Methods

Method	Description
GetConnection	Retrieve a connection by name
ListConnections	List connections with filtering and pagination
ListConnectionTypes	List all supported connection types

---

GetConnection

Retrieve a connection by name. Returns full connection details including credentials fetched from the secrets provider.

GET /v1/connections/{connection_id}

Path parameters

Field	Type	Required	Description
connection_id	string	Yes	ID portion of the connection resource name (e.g. prod-postgres for connections/prod-postgres)

Example

curl "https://api.cloud.firetiger.com/v1/connections/prod-postgres" \
  -u "$USERNAME:$PASSWORD"

---

ListConnections

List connections with optional filtering and pagination. Connection details are not populated in list responses.

GET /v1/connections

Query parameters

Field	Type	Required	Description
filter	string	No	Filter expression (e.g. connection_type="postgres")
order_by	string	No	Field to sort by
page_size	integer	No	Maximum results per page
page_token	string	No	Token for the next page of results
show_deleted	boolean	No	Include soft-deleted connections

Example

curl --get "https://api.cloud.firetiger.com/v1/connections" \
  -u "$USERNAME:$PASSWORD" \
  --data-urlencode 'filter=connection_type="postgres"' \
  --data-urlencode 'page_size=25'

---

ListConnectionTypes

List all supported connection types with their metadata and available tools. Returns only user-creatable types.

GET /v1/connection-types

Query parameters

Field	Type	Required	Description
filter	string	No	Filter expression
order_by	string	No	Sort order
page_size	integer	No	Maximum results per page
page_token	string	No	Token for the next page of results

Example

curl "https://api.cloud.firetiger.com/v1/connection-types" \
  -u "$USERNAME:$PASSWORD"

Response

{
  "types": [
    {
      "type": "CONNECTION_TYPE_POSTGRES",
      "displayName": "PostgreSQL",
      "description": "Query PostgreSQL databases",
      "availableTools": ["TOOL_POSTGRES_QUERY"]
    }
  ]
}

---

Integration OAuth and webhook methods

These methods are part of the firetiger.connections.v1 package and handle OAuth flows and webhook registration for specific integration types.

StartSlackOAuth

Initiate an OAuth flow to connect a Slack workspace.

POST /v1/slack-connections:startOAuth

HandleSlackEvent

Internal endpoint used by the Firetiger Integrations Server to forward Slack Events API webhooks to the appropriate deployment. Not intended for direct use; deployments authenticate the call via M2M credentials.

POST /v1/slack-connections:handleEvent

StartGithubOAuth

Initiate a GitHub App installation flow for a connection.

POST /v1/github-connections:startOAuth

Request body

Field	Type	Required	Description
connection_name	string	No	Existing connection name (format: connections/{connection_id}) when re-authorizing or expanding scopes on an existing GitHub install. Omit to create a new connection.
return_path	string	No	Relative UI path (must begin with /) to redirect to after the install completes. Defaults to /integrations/connections.

ListRepositories

List the repositories a GitHub connection’s installation can access. Used to populate a repository picker instead of free-text entry.

POST /v1/github-connections:listRepositories

Request body

Field	Type	Required	Description
connection_name	string	Yes	The GitHub connection (format: connections/{connection_id}) whose installation’s repositories to list.
page_size	int32	No	Maximum repositories to return in one page (AIP-158). Defaults to and is capped at 100; values ≤ 0 use the default.
page_token	string	No	Opaque token from a prior response’s next_page_token (AIP-158). Empty returns the first page.

Response body

Field	Type	Description
repositories	Repository[]	The repositories the installation can access.
next_page_token	string	Token to pass as page_token for the next page; empty when there are no more repositories (AIP-158).

Each Repository carries full_name (owner/repo), default_branch, and private.

ListRepositoryBranches

List the branches of a repository accessible to a connection’s installation, plus the repository’s default branch. Used to populate a branch picker.

POST /v1/github-connections:listBranches

Request body

Field	Type	Required	Description
connection_name	string	Yes	The GitHub connection (format: connections/{connection_id}) that grants access.
repository	string	Yes	The repository, in owner/repo form.
page_size	int32	No	Maximum branches to return in one page (AIP-158). Defaults to and is capped at 100; values ≤ 0 use the default.
page_token	string	No	Opaque token from a prior response’s next_page_token (AIP-158). Empty returns the first page.

Response body

Field	Type	Description
branches	string[]	Branch names on the repository.
default_branch	string	The repository’s default branch (e.g. main). Returned on every page.
next_page_token	string	Token to pass as page_token for the next page; empty when there are no more branches (AIP-158).

StartLinearOAuth

Initiate an OAuth flow to connect a Linear workspace.

POST /v1/linear-connections:startOAuth

HandleLinearEvent

Internal endpoint used by the Firetiger Integrations Server to forward Linear webhook events to the appropriate deployment. Not intended for direct use; deployments authenticate the call via M2M credentials.

POST /v1/linear-connections:handleEvent

CreateOrganizationInvitation

Create a Clerk organization invitation.

POST /v1/clerk-connections:createOrganizationInvitation

RegisterWebhook

Register an Incident.io webhook for a connection.

POST /v1/connections/{connection}:registerIncidentIoWebhook

RegisterPagerdutyWebhook

Mint a PagerDuty V3 webhook URL for a connection. Persists a rotation-safe token on the connection and returns the URL to paste into the PagerDuty webhook subscription. The signing secret is supplied separately via UpdateConnection after the user finishes configuring the PagerDuty side.

POST /v1/pagerduty-connections:registerWebhook

Auth. Requires a Clerk JWT (Authorization: Bearer <jwt>). Basic-auth callers cannot use this endpoint because the integrations server needs a deployment-scoped identity from JWT/M2M claims; the API server forwards the inbound auth header verbatim and Basic credentials do not carry that context. The Firetiger UI calls this method with a user JWT.

Request body

Field	Type	Required	Description
connection_name	string	Yes	Existing PagerDuty connection to attach the webhook to. Format: connections/{connection_id}.

Example

curl -X POST "$BASE_URL/v1/pagerduty-connections:registerWebhook" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"connection_name": "connections/abc-123"}'

Response

{
  "webhookUrl": "https://integrations.firetigerapi.com/pagerduty/webhook/dGhpc0lzQVRlc3RUb2tlbjEyMzQ1Njc4OTA",
  "webhookToken": "dGhpc0lzQVRlc3RUb2tlbjEyMzQ1Njc4OTA"
}