# Make your first request

> Make your first request with an HTTP proxy or SOCKS5 with remote DNS.
>
> Web page: https://ports.io/docs/guides/quickstart/
> Documentation index: https://ports.io/llms.txt

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

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](https://ports.io/docs/reference/protocols-and-limits.md) for transport details.

## 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

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

```sh
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.

```powershell
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

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](https://ports.io/docs/reference/troubleshooting.md).

## Choose your next step

- Use [curl](https://ports.io/docs/guides/curl.md), [Python](https://ports.io/docs/guides/python.md), or [JavaScript](https://ports.io/docs/guides/javascript.md) in your application.
- Add [country and region targeting](https://ports.io/docs/reference/username-reference.md).
- Keep related connections together with a [sticky or fixed session](https://ports.io/docs/reference/sessions.md).
- Read [usage measurement](https://ports.io/docs/guides/usage.md) before comparing proxy traffic with application payload sizes.