documentation/features/interceptor.mdx
You can access APIs blocked by Cross-Origin Resource Sharing (CORS) restriction by using either Hoppscotch Agent, Proxyscotch or custom middleware. You can also use the Hoppscotch web extension to intercept requests and responses.
The Hoppscotch Agent is a micro application designed to mitigate the challenges posed by `CORS` in modern web browsers. Acting as a local intermediary, it intercepts API requests made through the Hoppscotch web app and reroutes them through your local machine. This means that the Hoppscotch Agent handles requests using your local network configuration.
1. Download the Hoppscotch Agent for your operating system:
<AccordionGroup>
<Accordion title="Mac" icon="apple">
<Card title="Apple Silicon (.dmg)" href="https://github.com/hoppscotch/agent-releases/releases/latest/download/Hoppscotch_Agent_mac_aarch64.dmg">
Download for Apple Silicon-based Mac.
</Card>
<Card title="Intel (.dmg)" href="https://github.com/hoppscotch/agent-releases/releases/latest/download/Hoppscotch_Agent_mac_x64.dmg">
Download for Intel-based Mac.
</Card>
</Accordion>
<Accordion title="Windows" icon="windows">
<Card title="Windows Installer (.msi)" href="https://github.com/hoppscotch/agent-releases/releases/latest/download/Hoppscotch_Agent_win_x64.msi">
Download the installer for Windows (64-bit).
</Card>
<Card title="Windows Portable (.exe)" href="https://github.com/hoppscotch/agent-releases/releases/latest/download/Hoppscotch_Agent_win_x64_portable.zip">
Download the portable version for Windows (64-bit).
</Card>
</Accordion>
<Accordion title="Linux" icon="linux">
<Card title="Debian (.deb)" href="https://github.com/hoppscotch/agent-releases/releases/latest/download/Hoppscotch_Agent_linux_x64.deb">
Download the Debian package for Debian-based Linux distributions.
</Card>
<Card title="App Image (.AppImage)" href="https://github.com/hoppscotch/agent-releases/releases/latest/download/Hoppscotch_Agent_linux_x64.AppImage">
Download the AppImage for Linux.
</Card>
</Accordion>
</AccordionGroup>
2. Open [Hoppscotch](https://hoppscotch.io) app and navigate to the "**Interceptors**" section in the **"Settings"** page.
3. Locate the "**Agent**" option within the Interceptors section to initiate a connection to your local agent.
4. The application will prompt you for a "**One-Time Verification Code**". This verification code will be generated within the Hoppscotch Agent.
5. Enter the verification code into the application to establish a secure connection.
Once connected, all API requests made through the Hoppscotch web app will be routed through Hoppscotch agent, effectively eliminating CORS-related issues.
<Tip>Recommended interceptor for most users as it is compaitble with all platforms.</Tip>
A proxy server acts as an intermediary between your device and the internet, forwarding requests and responses to and from the desired API. By routing requests through a proxy, you can bypass CORS restrictions and access APIs that would otherwise be blocked by the browser.
- Enable proxy interceptor from "[**Settings page**](https://hoppscotch.io/settings)" under the **Interceptors** section.
- You can replace the default Proxy URL with your own proxy middleware if you wish or use [Proxyscotch](https://github.com/hoppscotch/proxyscotch), which acts as a remote proxy server for routing API requests.
## Proxyscotch
[Proxyscotch](https://github.com/hoppscotch/proxyscotch) is our official proxy server. It is an MIT licensed open-source project that can bypass Cross-Origin Resource Sharing (CORS) restrictions by routing API requests through a remotely hosted proxy, ensuring that requests originate from a trusted environment.
#### Self-Hosted Proxyscotch
To use Proxyscotch with a minimal setup, you can pull and run the official pre-built Docker image. This provides an instant proxy environment without requiring manual compilation or installation.
You can host Proxyscotch on your own server by following the instructions below:
```bash
# Pull the latest Proxyscotch image from Docker Hub
docker pull hoppscotch/proxyscotch
# Run the container in detached mode, exposing port 9159
docker run -d -p 9159:9159 --name proxyscotch hoppscotch/proxyscotch
```
#### Proxyscotch Installer
If you prefer a native installation, download and install both the Desktop and Server binaries for your operating system.
<AccordionGroup>
<Accordion title="Mac" icon="apple">
<Card title="Tray application (macOS)" href="https://github.com/hoppscotch/proxyscotch/releases/latest/download/Proxyscotch-Desktop-macOS-v0.1.1.zip">
Download proxyscotch for macOS desktops. This will install the tray application for seamless proxy management.
</Card>
<Card title="Proxy Server Binary (Intel-based macOS)" href="https://github.com/hoppscotch/proxyscotch/releases/latest/download/proxyscotch-server-darwin-amd64-v0.1.1">
Download the proxy server binary for Intel-based (x86-64) Macs.
</Card>
<Card title="Proxy Server Binary (Apple Silicon macOS)" href="https://github.com/hoppscotch/proxyscotch/releases/latest/download/proxyscotch-server-darwin-arm64-v0.1.1">
Download the proxy server binary for Apple Silicon-based (ARM64) Macs.
</Card>
</Accordion>
<Accordion title="Windows" icon="windows">
<Card title="Tray application (Windows - AMD)" href="https://github.com/hoppscotch/proxyscotch/releases/latest/download/Proxyscotch-Desktop-Windows-amd64-v0.1.1.exe">
Download proxyscotch for AMD-based Windows desktops. This will install the tray application for easy proxy management.
</Card>
<Card title="Proxy Server Binary (Windows - AMD)" href="https://github.com/hoppscotch/proxyscotch/releases/latest/download/proxyscotch-server-windows-amd64-v0.1.1.exe">
Download the proxy server binary for AMD-based Windows machines.
</Card>
<Card title="Tray application (Windows - ARM)" href="https://github.com/hoppscotch/proxyscotch/releases/latest/download/proxyscotch-arm64.exe">
Download proxyscotch for ARM-based Windows desktops. This will install the tray application for easy proxy management.
</Card>
<Card title="Proxy Server Binary (Windows - ARM)" href="https://github.com/hoppscotch/proxyscotch/releases/latest/download/proxyscotch-server-windows-arm64-v0.1.1.exe">
Download the proxy server binary for ARM-based Windows machines.
</Card>
</Accordion>
<Accordion title="Linux" icon="linux">
<Card title="Tray application (Linux - AMD)" href="https://github.com/hoppscotch/proxyscotch/releases/latest/download/Proxyscotch-Desktop-Linux-amd64-v0.1.1">
Download proxyscotch for AMD-based Linux desktops. This will install the tray application for seamless proxy management.
</Card>
<Card title="Proxy Server Binary (Linux - AMD)" href="https://github.com/hoppscotch/proxyscotch/releases/latest/download/proxyscotch-server-linux-amd64-v0.1.1">
Download the proxy server binary for AMD-based Linux machines.
</Card>
</Accordion>
</AccordionGroup>
<Note>
The proxy will add a **desktop application to your system tray**, providing quick access to various proxy settings such as setting the access token. After launching the application, a dialog will prompt you to complete the **certificate installation** process. For more details on how to install the certificate, [visit this wiki](https://github.com/hoppscotch/proxyscotch/wiki/Certificate-Installation).
Upon activation, the **server** will run in the background and interact with the proxy to route and manage requests.
</Note>
### Building Proxyscotch from Source
If you prefer to build and run Proxyscotch manually from source, you can clone the repository and compile the binaries for your platform.
```bash
git clone https://github.com/hoppscotch/proxyscotch.git
```
Follow the platform-specific instructions below to build the proxy and server from source for your operating system:
<AccordionGroup>
<Accordion title="Building on macOS" icon="apple">
```bash
# Build the desktop tray application
./build.sh darwin
# Build the standalone server application
./build.sh darwin server
```
</Accordion>
<Accordion title="Building on Windows" icon="windows">
You can use Git Bash to run the following commands:
```bash
# Build the desktop tray application
./build.sh windows
# Build the standalone server application
./build.sh windows server
```
</Accordion>
<Accordion title="Building on Linux" icon="linux">
```bash
# Build the desktop tray application
./build.sh linux
# Build the standalone server application
./build.sh linux server
```
</Accordion>
</AccordionGroup>
<Tip> After building, the compiled binaries will be available in the `out/` directory. </Tip>
#### Running the Proxyscotch Server
After building the server, use the following command to start the proxy server:
```bash
$ ./out/<platform>-server/server --host="<hostname>:<port>" --token="<token_or_blank>"
# e.g. on Linux
$ ./out/linux-server/server --host="localhost:9159" --token=""
# or on Windows
$ ./out/windows-server/server.exe --host="localhost:9159" --token=""
```
<Warning> When the **token is left blank**, it grants unrestricted access to your proxy server. While this might be convenient, please be aware of the potential security risks and consider whether this level of open access is appropriate for your use case. </Warning>
#### Available Server Options
After running the Proxyscotch server, you can customize its behavior using various command-line options.
| **Option** | **Description** |
| ----------------------------- | -------------------------------------------------------------------------- |
| `--host="<hostname>:<port>"` | Define the host and port (default: `localhost:9159`). |
| `--token="<token>"` | Set an access token to restrict proxy usage (leave blank for open access). |
| `--allowed-origins="*"` | Comma-separated list of allowed origins for CORS. |
| `--banned-outputs="<values>"` | Comma-separated list of response values to redact. |
| `--banned-dests="<hosts>"` | Comma-separated list of blocked destination hosts. |
### Configure Proxyscotch in Hoppscotch
Once the container is running or the server is active, configure Hoppscotch to use `http://localhost:9159` as the Proxy URL in the "**Settings**" page.
This setup will route all API requests through Proxyscotch, facilitating communication with APIs that enforce strict CORS policies.
Since `CORS` is as simple as adding some HTTP headers, it's only blocked by the browser. You can build some proxy-like component that will make a call for you and get the response from the desired API. You add it to the headers and then send it back to Hoppscotch.
### How to use the Browser Extension
1. Install the browser extension from the below links:
- [<Icon icon="chrome" iconType="solid" /> Chrome](https://chrome.google.com/webstore/detail/hoppscotch-browser-extens/amknoiejhlmhancpahfcfcfhllgkpbld?hl=en)
- [<Icon icon="firefox" iconType="solid" /> Firefox](https://addons.mozilla.org/en-US/firefox/addon/hoppscotch)
2. Click on the Hoppscotch Browser Extension icon from the browser toolbar and ensure that `hoppscotch.io` is in your active origins. If you are using Hoppscotch Self-Host, add your own domain as a new origin
<Frame>
</Frame>
3. Refresh the Hoppscotch web app.
4. Open the interceptor and change the middleware to the browser extension
You can either go to the settings and enable the use of the browser extension as shown below:
<Frame>
</Frame>
Or you can open the interceptor menu and change the middleware as shown below:
<Frame>
</Frame>
### Origins
The origin list defines the URLs that the extension can connect to. If you're using hoppscotch.io, then you do not need to add any other origins. However, if you are using a self-hosted instance, you should add the domain of your self-hosted instance as an active origin.