Skip to content

Gateway REST API bridge

The api provider lets an agent use the gateway's own REST API (the routes documented in the gateway's OpenAPI document) through two tools:

Tool Does
api_discover lists routes from the gateway's OpenAPI document: method, path, summary, group and parameter names. Filters: pathPrefix, method, keyword. limit up to 500, default 100
api_call mutating, high risk: calls one route, for every method including GET

There are exactly two tools rather than one per route, so the tool list never changes while a client is connected.

Configuration

Both tools call the gateway over loopback only, using a gateway API key you configure:

"api": {
  "gatewayApiKey": "<keyName>:<secret>",
  "baseUrl": null
}
  • gatewayApiKey is an Ignition gateway API key (created in the gateway's API Keys settings) in <keyName>:<secret> form, sent as X-Ignition-API-Token. It is masked on the settings page and always redacted by config_resource_read. Without it, both tools return a clear "no gateway API key configured" error.
  • baseUrl (optional) overrides the automatic http://localhost:<port>. It must resolve to a loopback host, or calls are refused.

The OpenAPI document is served at GET /openapi.json on the gateway and requires a key; api_discover uses the configured key to read it.

The bridge acts with the gateway API key's permissions

Every api_call runs with the authority of the configured gateway API key. Give that key only the permissions the integration needs, and scope api_call tightly in the mutation allowlist.

Why every call is a mutating call

api_call is classified as mutating for every method, including GET, so every call passes the read-only flag, the mutation allowlist and the audit log. With readOnly on, api_call is refused.

Allowlist targets are api/<METHOD><path>, for example:

api/POST/data/api/v1/scan/projects

Scope entries by route prefix, for example api/GET/ to allow read routes only.

Path checks

api_call decodes the path once (strict UTF-8) and then refuses absolute URLs, // host overrides, .. traversal (including encoded forms such as %2e%2e), dot-only segments, backslashes, query strings embedded in the path, and double encoding. The same canonical path is used for the allowlist check and for the request, so the path that was checked is always the path that is sent. Pass query parameters and the request body in the tool's own query and body arguments.

Responses

  • Responses are capped at 256 KiB; a larger one returns a clear error naming its actual size.
  • A response that is not UTF-8 text reports binary: true and sizeBytes only.

On a redundant pair, a mutating api_call is a Persistent write and is refused on a backup. See Redundant pairs.