Skip to content
ports.io
Get started

Make your first request

View as MarkdownDownload

Connect your client to an HTTP proxy or authenticated SOCKS5 endpoint with a routing username and your workspace’s secret key. This guide makes one HTTPS request using a rotating route.

Before you begin

Section titled “Before you begin”

You need access to a workspace, permission to create an API key, and the proxy endpoint assigned to your account. An owner or admin can create a key.

Set PORTS_PROXY_URL to your assigned proxy URL, including its scheme, hostname, and port. Obtain this URL before running the examples. It is separate from the console URL and from the destination website’s URL.

Proxy type URL format for curl
HTTP proxy http://HOST:PORT
HTTP proxy over TLS https://HOST:PORT
SOCKS5 with remote DNS socks5h://HOST:PORT

These are formats, not real endpoints. For SOCKS5, use the assigned SOCKS port and socks5h:// so the destination hostname reaches the proxy. curl’s socks5:// mode resolves locally and sends an IP address, which the gateway rejects. Destination URLs must use hostnames, even with remote DNS enabled.

The SOCKS port can differ from the HTTPS proxy port. socks5h:// does not add TLS to the proxy connection; changing the scheme of an HTTPS proxy URL while retaining its TLS-only port will not work. See Protocols and limits for transport details.

Create a key

Section titled “Create a key”
  1. Sign in to the console and select your workspace.
  2. Open API keys and select Create key.
  3. Give the key a recognizable name, such as Integration development, and choose when it expires.
  4. Copy the full rp1_... secret when it appears. The console shows it only once.
  5. Store the secret in your application’s secret store. Supply it to the examples as the PORTS_PROXY_KEY environment variable.

The full secret is the proxy password. A key name, key ID, or masked suffix cannot authenticate a request.

Send an HTTPS request

Section titled “Send an HTTPS request”

Use v1_rotate as the username. The username selects the route; the password authenticates your workspace’s key.

curl --proxy "$PORTS_PROXY_URL" \
  --proxy-user "v1_rotate:$PORTS_PROXY_KEY" \
  --connect-timeout 10 \
  --max-time 30 \
  https://example.com/

On Windows PowerShell, use the environment-variable syntax below and call curl.exe explicitly.

curl.exe --proxy "$env:PORTS_PROXY_URL" --proxy-user "v1_rotate:$env:PORTS_PROXY_KEY" --connect-timeout 10 --max-time 30 https://example.com/

The command works with any of the proxy URL formats above. --proxy-user supplies the routing username and full key for either HTTP Basic authentication or SOCKS5 username/password authentication. The client establishes the corresponding tunnel, then performs TLS with the HTTPS destination. An https:// HTTP proxy URL additionally protects the connection to the proxy with TLS. Keep certificate verification enabled.

These timeouts are client settings for the example. Adjust them to your application.

Recognize success

Section titled “Recognize success”

A successful request returns the destination’s response body. Successful HTTP or SOCKS5 tunnel setup by itself only means the tunnel opened; inspect the destination response to confirm the request succeeded.

If HTTP authentication fails with 407, or SOCKS5 reports authentication failure, check the full secret, key expiration, routing username, and workspace status. If SOCKS5 reports a connection-not-allowed reply, check that remote DNS is enabled and the destination is a hostname. See errors and troubleshooting.

Choose your next step

Section titled “Choose your next step”