Proxy HTTP Requests To Another Server

Beeceptor is a powerful MITM proxy (man-in-the-middle, or kind of a forward-proxy) that can take your API integration and testing to the next level. Assume that you are using a 3rd party API. By wrapping this API domain with Beeceptor's sub-domain (endpoint), you gain full control over the traffic passing through it. This enables you to inspect and mock requests in real-time, giving you unprecedented flexibility in testing and debugging these API integrations. Check out the following illustration.

Beeceptor serves as a powerful MITM (Man-in-the-Middle) proxy, allowing you to intercept and analyze API traffic between your application and the server. In the provided illustration, a user interacts with a mobile app by clicking a button, which triggers an API call to the server. By accessing the Beeceptor dashboard, you gain the ability to intercept and inspect the request payload in this scenario.

You can inspect payloads for all the API calls (Rest/SOAP/HTTP) originating from your application, mock a few requests, change response data, simulate high latency, and even test API failure scenarios. This flexibility allows you to thoroughly test your application under a wide range of conditions.

Configuring proxy

When proxy is configured, requests that do not match a mock rule are forwarded to the target domain. In addition, you can view these requests and response payloads on the Dashboard.

Here is how you can update an endpoint to be a proxy for your target API domain.

Add a Backend Path Prefix

If your backend URL includes a fixed base path, open Routing and select Forward Requests. Set Target Domain to the backend domain, including http:// or https://, such as https://api.acme.com. Enter the base path, such as /payments, in the optional Path Prefix field. Beeceptor adds this prefix before the incoming request path. Leave it empty to forward the path as received.

Click Save to apply the routing configuration. For a mock server at https://my-api.proxy.beeceptor.com, the URLs map as follows:

Incoming request	Forwarded request
https://my-api.proxy.beeceptor.com/products/123?limit=10	https://api.acme.com/payments/products/123?limit=10

The popup shows an example when you enter a valid prefix. The shared request path is muted in both URLs so you can see which part is added.

Routing configuration for a Beeceptor proxy endpoint, forwarding requests to https://api.acme.com with the /payments path prefix.

Leave Path Prefix empty to forward the original path. A leading slash is added if missing, and trailing slashes are removed. A prefix of / also behaves as empty. Use a fixed path without query strings, fragments, spaces, templates, or traversal segments such as ...

Mock rules match the original incoming path and take priority. Only unmatched requests are forwarded. The incoming HTTP method, headers, body, encoded path, and query parameters are preserved, subject to any configured Global Headers.

Configure a Prefix Through the V2 API

The V2 Settings API accepts the existing proxy.targetUrl field and the optional proxy.pathPrefix field:

{
  "proxy": {
    "targetUrl": "https://api.acme.com",
    "pathPrefix": "/payments"
  }
}

Omit pathPrefix in a PATCH to keep its current value. Send an empty string to clear it. The existing targetUrl field and its behavior remain unchanged.

Global Headers

The Global Headers feature in Beeceptor allows you to modify (or “patch”) HTTP request and response headers when using Beeceptor as a domain proxy. This powerful capability enables seamless header manipulation without requiring any changes to the client-side code or backend services.

When requests pass through a Beeceptor proxy domain, Global Headers ensure that specific headers are automatically added or modified—either before forwarding the request to the target domain or before sending the response back to the caller. This operation is fully transparent to both the original request sender and the target server, making it ideal for use cases like authentication, debugging, or handling CORS-related issues.

How It Works

Suppose you have configured Beeceptor as a proxy domain: https://api-service.proxy.beeceptor.com. And this domain is proxying requests to a target domain: https://api.stripe.com. Using the Global Headers feature:

• You can define request headers (e.g., Authorization, X-Custom-Token) that will automatically be added or modified before the request is forwarded to api.stripe.com.
• You can also define response headers (e.g., Access-Control-Allow-Origin, X-Debug-Trace) that will be injected into the response before it is returned to the client.

Neither the client (caller) nor the destination API is aware of this header manipulation. This makes the feature highly useful for temporary testing, debugging, or even production-layer header injection.

Popular use cases

Here are some use cases for Global Headers:

1. Inject Auth Tokens or API Keys: Add Authorization headers (like Bearer <token>) to requests passing through Beeceptor. This helps simulate authenticated calls without changing the client or managing real user sessions.
2. Add Request Tracing for Debugging: Insert headers like X-Trace-Id or X-Debug-Mode: true to trace requests across services or enable conditional logging in test environments.
3. Simulate Roles or Feature Flags: Use custom headers (e.g., X-User-Role: admin) to mimic user roles, feature access, or test configurations. This is great for validating RBAC flows or toggling experimental features.
4. Bypass or Debug CORS Issues: Override response headers such as Access-Control-Allow-Origin and Access-Control-Allow-Headers to allow frontend apps to test cross-origin requests, even when the backend isn’t CORS-ready.
5. Manage Cookies and Session States: Modify or inject Set-Cookie headers in responses to simulate session expiration, login states, or cookie-based feature controls without changing application code.
6. Force Content-Type or Language Variants: Adjust Accept, Content-Type, or Accept-Language headers to test content negotiation. Useful for validating localization, media-type support, or fallback logic.

When to use proxying

Proxying is an interesting feature that help you discover hidden bugs during systems integration testing. Here are a few such cases explained.

Simulate slow external API response

E.g. If you are calling an external API and want to test scenarios around how does the your product/code behaves when the external API is slow to respond? You can wrap external API endpoint under a Beeceptor endpoint and create a mocking rule to delay all responses, say by 5 seconds.

Test failure code paths

As a QA engineer, you have no control to simulate failure scenarios of an external API and test your product/code to see how it will behave. In short, the code paths dealing with error scenarios are never tested. You can wrap external API endpoint under a Beeceptor endpoint and create a mocking rule to return 500 server error or 502 gateway error.

Performance testing

You can save cost by not calling external APIs during performance testing. E.g. do you really need to send emails notifications via an external service (and incur usage cost) when performance testing your application? You can mock the API responses as 200 using Beeceptor without triggering any external API (in this example email APIs).

SSL Validation Issues

In case you are facing SSL validations issues, you can use HTTP proxy with 'Ignore SSL Errors' setup to unblock an integration. Here, Beeceptor acts as a bridge between your application and external APIs, making it easy to intercept and examine HTTP traffic in real time, and ignoring SSL validations. Checkout our detailed post: Ignore SSL Errors.

Note: For more precise control over proxy behavior or to route requests to multiple endpoints, consider using Proxy or Callout Rule.

Service Virtualization

Service virtualization is the act of creating a replica of a service or deploying a mock service to reduce dependencies. Beeceptor makes this process simple by providing an intuitive interface for editing recorded responses to meet your specific requirements. Check out the video below for an example of how to set up a service virtualization scenario with Beeceptor.