HTTP

The connector runs a healthcheck server on port 8080 to let clients determine if the proxy is operational. As a result, you cannot create a listener on port 8080 to connect to an HTTP resource.

Connect to an HTTP Resource

To connect to an HTTP Resource, follow these steps:

Adjust the Hostname: In your API request, modify the hostname to point to the Connector. Replace the hostname with the http resource name you have specified in the resources section of the Control Plane or Terraform. If the hostname of your connector is formalcloud.net, and your http resource name is stripe, you can replace the request URL with the following:
- Old Way: https://api.stripe.com/v1/customers
- New Way (Using the Connector): https://stripe.formalcloud.net/v1/customers

Tool of Your Preference: Use your preferred API tool to send requests through the Connector. This can be tools like Postman, cURL, or any other HTTP client that allows you to specify the API endpoint. In order to see the user who made the request, you can set X-Formal-User-Username and X-Formal-User-Password in the request headers.

Payload Encryption

The Connector encrypts both response and request payloads before they’re sent to the Formal Control Plane. This ensures that Formal won’t have access to any transmitted data. Create a log configuration to enable payload encryption.

Decrypting the logs in Formal UI

First, deploy the AWS Lambda function using the code found here.
Then, navigate to a specific HTTP Log and hit the Decrypt Response Body or Decrypt Request Body to input the URL of the Lambda function directly in the UI.

You can watch a demo of this feature here.

HTTP Payload Size Limitation

To ensure efficient and streamlined logging while preventing potential issues related to large data volumes, our system provides configurable size limitations for both HTTP request and response payloads. If the size of a payload exceeds the configured limit, it will not be included in the logs. Create a log configuration to enable limits on payload sizes.

Multiple Resources

The Connector supports connecting multiple downstream APIs to the same Connector. For example, using a Connector with the hostname test-http-proxy.formalcloud.net, you can query:

- `stripe.test-http-proxy.formalcloud.net`
- `openai.test-http-proxy.formalcloud.net`

Which will then redirect traffic to the following resources:

- api.stripe.com
- api.openai.com

First Step

Configure your DNS entries with the subdomains.

Second Step

Create HTTP resources with names matching the subdomains used in the hostname of the Connector. In the example provided, the names of the resources should be openai and stripe.

Third Step

Link multiple resources to the same port.

The TLS Certificate must be a wildcard certificate and should cover every subdomain.

Policy Evaluation

Formal supports the following policy evaluation stages for HTTP:

Session: Evaluate and enforce policies at connection time. Actions: allow, block.
Request: Evaluate and enforce policies before request execution. Actions: allow, block, rewrite, decrypt.
Response: Evaluate and enforce policies after data retrieval. Actions: allow, filter, mask, rewrite, encrypt.

Use encrypt and decrypt to seal secrets such as OAuth tokens on the Connector. See Token Encryption and Encrypt & Decrypt. For an MCP worked example, see Encrypt MCP OAuth Tokens.

Header Rewrites

The rewrite action at the request stage adds, replaces, or removes HTTP headers before the request reaches the upstream service. Common use cases include injecting authentication tokens, enforcing organization-level API restrictions, and stripping internal headers. For Anthropic tenant restrictions, see Restrict Anthropic Sign-Ins to One Org.

Header names in input.http.headers are normalized to lowercase. The rewrite applies canonical HTTP casing before forwarding (e.g., x-custom-header becomes X-Custom-Header).

Add a header

package formal.v2

import future.keywords.if

rewritten_headers := object.union(input.http.headers, {
  "x-org-id": ["org-123"],
})

request := {
  "action": "rewrite",
  "headers": rewritten_headers,
} if {
  input.resource.technology == "http"
}

Header values must be arrays of strings. object.union merges the new headers into the existing input.http.headers; keys in the second object overwrite keys in the first.

Replace an existing header

The same object.union pattern overwrites a header value:

package formal.v2

import future.keywords.if

rewritten_headers := object.union(input.http.headers, {
  "authorization": ["Bearer <YOUR_SERVICE_TOKEN>"],
})

request := {
  "action": "rewrite",
  "headers": rewritten_headers,
} if {
  input.resource.technology == "http"
}

Remove a header

Setting a header to an empty array removes it before the request is forwarded:

package formal.v2

import future.keywords.if

rewritten_headers := object.union(input.http.headers, {
  "x-debug": [],
})

request := {
  "action": "rewrite",
  "headers": rewritten_headers,
} if {
  input.resource.technology == "http"
}

Formal logs both received and sent headers for each request. Rewrite behavior is visible in the Logs page.

Body Rewrites

The rewrite action can replace an entire HTTP request or response body. At each stage, input.http describes the message being evaluated. Each rewrite action supports one body field:

Field	Policy input	Behavior
`body`	`input.http.body`	Writes the string exactly.
`json`	`input.http.json`	Serializes a JSON value.
`post_form`	`input.http.post_form`	Rewrites HTML form fields.

Formal rejects actions that set more than one of body, json, or post_form.

Text bodies

The body field replaces plain text, XML, or another body represented as a string:

package formal.v2

import future.keywords.if

request := {
  "action": "rewrite",
  "body": "replacement text",
} if {
  input.resource.technology == "http"
  input.http.path == "/messages"
}

An empty string clears the body.

JSON bodies

The request or response must contain valid JSON and use a JSON content type. Formal then exposes the parsed value as input.http.json. object.union replaces selected fields while preserving the remaining object:

package formal.v2

import future.keywords.if

rewritten_json := object.union(input.http.json, {
  "password": "redacted",
})

request := {
  "action": "rewrite",
  "json": rewritten_json,
} if {
  input.resource.technology == "http"
  input.http.path == "/users"
}

Rego’s json.patch built-in supports nested changes and array operations. It accepts standard JSON Patch operations. The following patch replaces a nested value, removes a field, and appends an array item:

package formal.v2

import future.keywords.if

patched_json := json.patch(input.http.json, [
  {
    "op": "replace",
    "path": "/profile/email",
    "value": "redacted",
  },
  {
    "op": "remove",
    "path": "/internal_note",
  },
  {
    "op": "add",
    "path": "/labels/-",
    "value": "reviewed",
  },
])

request := {
  "action": "rewrite",
  "json": patched_json,
} if {
  input.resource.technology == "http"
  input.http.path == "/users"
}

Patch paths use slash-separated keys, such as /profile/email. All operations apply atomically. If any operation fails, json.patch is undefined and this rewrite does not apply. The Rego documentation describes JSON object syntax and access. Its object built-ins include object.get, object.remove, object.union, and related functions. If the body or content type does not qualify, input.http.json is absent. The raw string remains available as input.http.body.

HTML form bodies

Formal exposes parsed HTML form fields as input.http.post_form. Each field contains an array because a form can repeat keys.

package formal.v2

import future.keywords.if

rewritten_form := object.union(input.http.post_form, {
  "password": ["redacted"],
})

request := {
  "action": "rewrite",
  "post_form": rewritten_form,
} if {
  input.resource.technology == "http"
  input.http.path == "/login"
}

Repeated values use string arrays, such as {"scope": ["read", "write"]}.

Response bodies

A response rule supports the same fields. At this stage, input.http.body, input.http.json, and input.http.post_form describe the upstream response.

package formal.v2

import future.keywords.if

response := {
  "action": "rewrite",
  "json": object.union(input.http.json, {
    "internal_note": "redacted",
  }),
} if {
  input.resource.technology == "http"
  input.http.path == "/accounts"
}

Formal logs the original body as received and the rewritten body as sent. The Logs page displays both values.

Authentication

The Connector supports forwarding HTTP authentication headers transparently from HTTP clients. In addition, the Connector supports adding HTTP authentication headers that the HTTP client does not have access to using Native Users.

Native Users

The connector can inject credentials for the upstream Resource using Native Users. Choose one of these typed credential methods:

HTTP Basic injects a username and password into a named header.
HTTP Bearer injects a bearer token into a named header.
API Key (Header) injects a key into a named request header.
API Key (Query) injects a key into a named query parameter.

Terraform

Use the Terraform block that matches the credential method.

HTTP Basic

resource "formal_native_user_v3" "http_basic" {
  resource_id = formal_resource.api.id
  label       = "basic-auth"

  http_basic {
    header   = "Authorization"
    username = "api_user"
    password {
      environment_variable = "HTTP_BASIC_PASSWORD"
    }
  }
}

HTTP Bearer

resource "formal_native_user_v3" "http_bearer" {
  resource_id = formal_resource.api.id
  label       = "bearer"

  http_bearer {
    header = "Authorization"
    token {
      environment_variable = "HTTP_BEARER_TOKEN"
    }
  }
}

API Key (Header)

resource "formal_native_user_v3" "http_api_key_header" {
  resource_id = formal_resource.api.id
  label       = "header-api-key"

  http_api_key_header {
    key = "X-Api-Key"
    value {
      environment_variable = "HTTP_API_KEY_HEADER"
    }
  }
}

API Key (Query)

resource "formal_native_user_v3" "http_api_key_query" {
  resource_id = formal_resource.api.id
  label       = "query-api-key"

  http_api_key_query {
    key = "api_key"
    value {
      environment_variable = "HTTP_API_KEY_QUERY"
    }
  }
}

Each secret can be stored in the Formal control plane, read from a Connector environment variable, or returned by a connection-time hook. See Select a default Native User for selection examples.

If an HTTP Resource has no Native Users configured, the Connector forwards requests upstream without injecting credentials.

Resources that still use JSON documents in the password field use the legacy Native User format.

To seal client-held OAuth tokens so they leave the Connector as formalsealed:v1: envelopes, configure Token Encryption and use the HTTP encrypt and decrypt policy actions.

Getting Started

Example Use Cases

AI Governance

Configuring Formal

Integrations

Configuration

Connect to an HTTP Resource

Payload Encryption

Decrypting the logs in Formal UI

HTTP Payload Size Limitation

Multiple Resources

Policy Evaluation

Header Rewrites

Add a header

Replace an existing header

Remove a header

Body Rewrites

Text bodies

JSON bodies

HTML form bodies

Response bodies

Authentication

Native Users

Terraform

HTTP Basic

HTTP Bearer

API Key (Header)

API Key (Query)

​Connect to an HTTP Resource

​Payload Encryption

​Decrypting the logs in Formal UI

​HTTP Payload Size Limitation

​Multiple Resources

​Policy Evaluation

​Header Rewrites

​Add a header

​Replace an existing header

​Remove a header

​Body Rewrites

​Text bodies

​JSON bodies

​HTML form bodies

​Response bodies

​Authentication

​Native Users

​Terraform

HTTP Basic

HTTP Bearer

API Key (Header)

API Key (Query)

Connect to an HTTP Resource

Payload Encryption

Decrypting the logs in Formal UI

HTTP Payload Size Limitation

Multiple Resources

Policy Evaluation

Header Rewrites

Add a header

Replace an existing header

Remove a header

Body Rewrites

Text bodies

JSON bodies

HTML form bodies

Response bodies

Authentication

Native Users

Terraform