Skip to main content
REST API connections let an agent call a service’s REST or GraphQL API using its own account. Formation supplies authentication through a configured connection; the agent refers to that connection’s request tool and never supplies its token in tool arguments.

​
Connect an API

Open the agent’s Tools page, choose Add tool, then Custom REST API.
  1. Give the connection a recognizable name and its public HTTPS API base URL.
  2. Enter a token for this agent’s own service account.
  3. Choose the authentication header and prefix. The defaults send Authorization: Bearer <token>. For an API using X-API-Key: <token>, set the header to X-API-Key and clear the prefix.
  4. Add a description of the API’s purpose and, optionally, a documentation URL.
  5. Save the connection. It becomes available immediately; saving does not make an API request or prove that the service accepts the credential.
Each acting account belongs to one agent. Two agents may use the same API endpoint through their own accounts. Infrastructure defaults and another agent’s credentials are never inherited by an API connection.

​
What the agent sees

Each enabled connection contributes one authenticated request tool to normal tool discovery. Its description identifies the connection, base URL, purpose, and supplied documentation. The agent can search for it with tool_search and send requests with a method, relative path, optional query parameters, headers, and body. A GraphQL API uses the same tool with a POST body containing the query and variables. An arbitrary REST API does not advertise an MCP-style tool catalog. Formation does not automatically discover endpoints, import OpenAPI schemas, or infer named operations. Documentation and the connection description guide the agent’s requests. The documentation URL is a reference, not an instruction to fetch or execute content during setup. The connection’s URL and configured authentication cannot be replaced by tool arguments. Requests stay within its base path and use the token in its configured header. A custom header/prefix supports API keys as well as bearer tokens; OAuth refresh, request signing, query-string credentials, and cookie-based authentication are outside this initial adapter.

​
Credential and request boundaries

Tokens are encrypted in Formation’s existing agent-owned secret store and covered by master-key rotation. Operator reads return credential presence, never its value. When editing, leaving the token blank preserves the saved value while the API base URL is unchanged. Changing that destination requires entering the token again. Disable a connection to prevent subsequent requests, or delete it to remove the connection and stored credential. Neither action revokes the token at the service. A fixed HTTP worker executes each request in a separate process without the installation master key, database credentials, or unrelated secrets. It receives only the selected request and credential over a private input pipe. Tokens are not delivered to workspaces or exposed as command arguments or environment variables. Only public HTTPS destinations on the default HTTPS port are supported. DNS is checked immediately before dialing, environment proxies are ignored, and redirects are not followed. Private-network APIs require a separately designed trust policy. Request and response sizes and execution time are bounded. Responses redact exact delivered credential values. This helps prevent accidental reflection; it does not guarantee a remote service cannot encode a credential into its response. The credential’s service permissions determine what the agent can do. A base URL restriction alone does not make an API read only, and GraphQL queries and mutations can use the same POST endpoint. All API requests are recorded as externally effectful and are not automatically replayed after an uncertain outcome. They retain the triggering conversation’s source restrictions in the tool evidence ledger.

​
Operator API

Use the existing connection API. Create a connection with adapter: "http_api" and name, base_url, token, optional auth_header, auth_prefix, description, and documentation_url. The managed connection has an api metadata object and supports update, enable, disable, and delete actions. Updates require its current version. An omitted prefix uses Bearer when creating a connection; an explicitly empty prefix sends the raw token. A prefix containing words is separated from the token by one space. API connections do not grant workspace credential delivery or access to another agent’s account.