OpenAPI Connections

OpenAPI connections let agents interact with any REST API that publishes an OpenAPI (Swagger) specification. Agents can introspect the spec to discover available endpoints and make authenticated requests.

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

When to use OpenAPI vs HTTP

	OpenAPI	HTTP
Endpoint discovery	Agents read the spec to find endpoints	You list endpoints in the description
Route restrictions	Requests are validated against the server domain	You configure explicit `allowed_routes`
Best for	APIs with published OpenAPI specs	APIs without specs, or when you need fine-grained route control

Connection Parameters

Required Parameters

Parameter	Type	Description
`spec_url`	string	URL to fetch the OpenAPI specification (JSON or YAML)

Optional Parameters

Parameter	Type	Description
`server_url`	string	Base URL of the API server. If omitted, derived from the spec’s `servers[0].url`

Authentication

Authentication is configured via the auth oneof — set exactly one of the following methods. These reuse the same auth types as HTTP connections.

OAuth Client Credentials

Automatically obtains and refreshes an OAuth 2.0 access token using the client credentials grant.

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

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"
}

Agent Tools

OpenAPI connections provide two tools to agents:

`openapi_schema`

Introspects the OpenAPI spec. With no path, returns a summary of all available endpoints. With a path (e.g. /users), returns the full schema including parameters, request body, and response schemas.

`openapi_request`

Makes an HTTP request to the API. The agent provides a full URL (e.g. https://api.example.com/v1/users), which is validated against the configured server domain to prevent credential leakage.

Server URL Resolution

When server_url is omitted, the server URL is resolved from the spec:

The spec is fetched from spec_url
servers[0].url is extracted
If the server URL is relative (e.g. /v1), it is resolved against the spec URL

For example, a spec at https://api.example.com/openapi.json with servers: [{url: "/v1"}] resolves to https://api.example.com/v1.

Example Connection

{
  "display_name": "Vanta API",
  "description": "Vanta compliance platform API",
  "connection_details": {
    "openapi": {
      "spec_url": "https://firetiger-public.s3.us-west-2.amazonaws.com/connections/vanta/openapi.json",
      "server_url": "https://api.vanta.com/v1",
      "oauth_client_credentials": {
        "token_url": "https://api.vanta.com/oauth/token",
        "client_id": "my-client-id",
        "client_secret": "my-client-secret",
        "scopes": "vanta-api.all:read"
      }
    }
  }
}

Best Practices

Prefer OAuth - Use OAuth Client Credentials when the API supports it for automatic token refresh
Set server_url explicitly - While it can be derived from the spec, setting it explicitly avoids extra network calls
Use openapi_schema first - Agents should introspect the spec before making requests to understand available endpoints and parameters