Forward Proxy

The Forward Proxy feature allows you to route traffic from your applications and systems through Beeceptor for traffic interception, inspection, and mocking. This powerful capability enables you to intercept both HTTP and HTTPS requests from any configured client and manage mock responses directly from the Beeceptor dashboard.

Plan Availability

The Forward Proxy feature is available on Scale and Enterprise plans only.

How It Works

Beeceptor Forward Proxy operates as an HTTP proxy that supports both HTTP and HTTPS traffic.

For HTTPS requests:

1. The client sends a CONNECT request to the proxy.
2. Beeceptor establishes a secure connection.
3. Traffic is decrypted and inspected.
4. The request is either forwarded upstream or matched with a mock rule.

Because HTTPS traffic is decrypted for inspection, you must install and trust the Beeceptor Proxy CA certificate on the client device.

Getting Started

You need two things before routing traffic:

1. A proxy authentication password
2. The Beeceptor Proxy CA certificate

Step 1: Configure the Proxy Password

The first step is to configure the authentication password for your forward proxy in the endpoint settings. Each endpoint has its own forward proxy credentials.

1. Open your endpoint.
2. Go to Settings.
3. Scroll to Forward Proxy Configuration.
4. Click Set Password.
5. Save the generated password securely.

The password is shown only once. If lost, you should reset it. This will be used as the authentication credential when configuring any client (browser, terminal, or system) is instructed to use the forward proxy.

Step 2: Obtain the Proxy Certificate

To intercept HTTPS traffic, the client must trust Beeceptor’s Proxy CA.

1. In Forward Proxy Configuration
2. Click Download Certificate
3. Install it on your system or device

Client Configuration

You can route traffic through Beeceptor in multiple ways. Choose the configuration method that fits your workflow:

• Browser-level debugging
• CLI or backend testing
• System-wide routing
• Mobile device testing

Each option gives you full traffic visibility inside your Beeceptor endpoint console.

Chrome Browser

Launching Chrome with proxy flags is the fastest way to verify your Forward Proxy setup. It isolates the proxy configuration to a temporary browser profile, so your main Chrome setup remains untouched.

Prerequisites

Before launching Chrome:

1. Install and trust the Beeceptor Proxy CA certificate on your system
2. Keep your endpoint name and proxy password ready
3. Choose the Chrome Binary

Choose the Chrome Binary

Use the appropriate executable for your platform:

• macOS: /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
• Linux: google-chrome
• Windows (PowerShell): & 'C:\Program Files\Google\Chrome\Application\chrome.exe'

Launch Chrom

## macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --proxy-server=http://forward-proxy.beeceptor.com:8443 \
  --no-first-run \
  --no-default-browser-check \
  --disable-background-networking \
  --disable-sync \
  --user-data-dir=/tmp/beeceptor-chrome \
  https://echo.free.beeceptor.com/

## Linux
google-chrome \
  --proxy-server=http://forward-proxy.beeceptor.com:8443 \
  --no-first-run \
  --no-default-browser-check \
  --disable-background-networking \
  --disable-sync \
  --user-data-dir=/tmp/beeceptor-chrome \
  https://echo.free.beeceptor.com/

## Windows (PowerShell)

& 'C:\Program Files\Google\Chrome\Application\chrome.exe' `
  --proxy-server=http://forward-proxy.beeceptor.com:8443 `
  --no-first-run `
  --no-default-browser-check `
  --disable-background-networking `
  --disable-sync `
  --user-data-dir=$env:TEMP\beeceptor-chrome `
  https://echo.free.beeceptor.com/

Terminal / Shell

If you are testing backend services, SDKs, CLI tools, or scripts, environment variables are the simplest option.

Set proxy variables in your shell:

# http traffic
export http_proxy=http://[ENDPOINT_NAME]:[PASSWORD]@forward-proxy.beeceptor.com:8443

# https traffic
export https_proxy=http://[ENDPOINT_NAME]:[PASSWORD]@forward-proxy.beeceptor.com:8443

Testing the Configuration:

Once configured, test with curl or any HTTP client:

curl https://echo.free.beeceptor.com/

If configured correctly:

• The request appears in Beeceptor endpoint's console.
• The echo service responds with request details.
• HTTPS traffic is decrypted and visible.

You can now debug real API calls directly from your terminal.

macOS System

If you want to route all system traffic through Beeceptor, configure proxy settings at the OS level.

Install Certificate (macOS)

To properly inspect HTTPS traffic, install and trust the CA certificate:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/beeceptor-proxy-ca-com.pem

Enter your macOS password when prompted.

Configure macOS Proxy Settings

To route all system traffic through the forward proxy on macOS, configure it in System Preferences.

Steps:

1. Open System Settings → Network
2. Select active connection (Wi-Fi or Ethernet)
3. Click Details
4. Open the Proxies tab
5. Enable:
   • Web Proxy (HTTP)
   • Secure Web Proxy (HTTPS)
6. Configure both:
   • Server: forward-proxy.beeceptor.com
   • Port: 8443
   • Username: Endpoint name
   • Password: Proxy password
7. Click OK, click Apply

Verification

Open a browser and navigate to:

https://echo.free.beeceptor.com/

You should:

• See authentication prompt
• See request in Beeceptor Console
• Receive echo response with request details

All system traffic is now routed through Beeceptor.

Android System

Forward Proxy also works on mobile devices. This helps when testing mobile apps that communicate with external APIs.

Install Certificate on Android

For HTTPS traffic interception, install the Beeceptor Proxy CA certificate on your Android device.

Steps:

1. Download the certificate from your endpoint settings to your Android device
2. Open Settings → Security → Encryption & credentials → Install from storage
3. Select the downloaded certificate file (e.g., beeceptor-proxy-ca-com.pem)
4. Follow the prompts to name the certificate and complete the installation

Configure Android Wi-Fi Proxy

To route all traffic through the forward proxy on Android, configure it in your network settings.

Steps:

1. Open Settings → Network and Internet → Wi-Fi
2. Go to active Wi-Fi network and tap the Settings icon
3. Click on Edit (pencil icon) to modify the network
4. Under Advanced Options → Proxy, select Manual
5. Enter:
   • Proxy hostname: forward-proxy.beeceptor.com
   • Proxy port: 8443
6. Tap Save

Verification

Open Chrome on the device and visit:

https://echo.free.beeceptor.com/

Authenticate with:

• Username → Endpoint name
• Password → Proxy password

Traffic Interception

Once your client is configured to use Beeceptor as a forward proxy, every outgoing HTTP and HTTPS request flows through your endpoint before reaching the destination server.

This gives you full visibility into how your application communicates with external APIs in real time. Instead of guessing what your code is sending, you can now see the exact request as it leaves your system, including headers, payload, and timing information.

Real-Time Request Capture

1. Navigate to your endpoint's Console page
2. All requests routed through the forward proxy will appear in the Requests table
3. Each row shows:
   • Timestamp - When the request was received
   • Method - HTTP method (GET, POST, etc.)
   • Host - Target domain (e.g., google.com)
   • Path - Request path
   • Status Code - Response status (if received)

Host-Level Filtering

When your application communicates with multiple external services, the Console may show traffic for many domains.

Use the Host Filter dropdown to narrow down requests to a specific upstream service.

For example, if your app talks to:

• A payment provider
• A logging service
• An analytics API

You can filter and focus on just one integration at a time. This reduces noise and speeds up debugging.

Mocking Specific Requests

Intercepting traffic gives you visibility. Mocking gives you control. The forward proxy integrates seamlessly with Beeceptor's mocking system. You can create mock rules to respond with custom data or behavuor instead of forwarding requests to the upstream server.

You can create different types of mock rules based on your testing needs:

• Static responses for fixed payloads
• Dynamic responses using request parameters and templating
• Stateful behavior to simulate multi-step workflows
• Conditional rules based on headers, body content, query parameters, or path matching

These request-based filters give you precise control to device which requests are mocked and which are allowed to pass through to the upstream server.