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 Formal console 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.

Automatic detection of PII

The Connector can automatically detect PII in request and response JSON payloads such that policies can be applied to redact or block such traffic. To do so, the Connector employs machine learning models hosted by the Data Classifier Satellite. You can choose whether the Satellite should use an LLM model or a custom NLP model built by Formal in its startup options. The Connector supports dynamically choosing the model using HTTP header. You can set the X-Formal-Request-Pii-Classifier and X-Formal-Response-Pii-Classifier headers to llm, nlp, or none to choose the model type. If the header is not set, the Connector will use the NLP model.

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.

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

To create native users, a JSON object is used as the password. Formal Connector with HTTP Resource supports various authentication methods, including Basic, API Key, and Bearer Token.

Basic Authentication: This method is suitable for scenarios where a simple username and password are adequate for authentication. The configuration for Basic Authentication in Formal is as follows:

{"type": "http", "sub_type": "basic", "http_basic": { "header": "Authorization", "username": "<username>", "password": "<password>"}}

API Key: When using an API key for authentication, you can specify the key in the request header. This method is typically used when interacting with APIs that require a secret key for access. The configuration is as follows:

{"type": "http", "sub_type": "api_key", "http_api_key": { "type": "header", "key": "Authorization", "value": "<value>"}}

Bearer token: Bearer Token authentication is a common method used in OAuth 2.0 and other authorization frameworks. It involves sending a token in the request header to authenticate requests. The configuration for Bearer Token authentication in Formal is:

{"type": "http", "sub_type": "bearer_token", "http_bearer_token": { "header": "Authorization", "token": "<token>"}} The corresponding authentication details will then be passed to the underlying resource, ensuring that access is securely controlled based on the specified method. 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.

Types

Authentication

Name	Type
type	STRING
sub_type	ENUM[“http_bearer_token”, “http_api_key”, “http_basic”]
http_bearer_token	BearerToken
http_api_key	ApiKey
http_basic	Basic

Api Key

Name	Type
type	ENUM[“query_params”, “header”]
key	STRING
value	STRING

Bearer token

Name	Type
header	STRING
token	STRING

Basic

Name	Type
header	STRING
username	STRING
password	STRING

Getting Started

Configuring Formal

Leveraging Formal

Integrations

Configuration

Client Apps

Example Use Cases

Connect to an HTTP Resource

Payload Encryption

Decrypting the logs in Formal UI

Automatic detection of PII

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

Types

Authentication

Api Key

Bearer token

Basic

​Connect to an HTTP Resource

​Payload Encryption

​Decrypting the logs in Formal UI

​Automatic detection of PII

​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

​Types

​Authentication

​Api Key

​Bearer token

​Basic

Connect to an HTTP Resource

Payload Encryption

Decrypting the logs in Formal UI

Automatic detection of PII

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

Types

Authentication

Api Key

Bearer token

Basic