# ports.io documentation

> Connect your application to ports.io residential proxies: authenticate, choose a location, keep a session, and understand your usage.
>
> Web page: https://ports.io/docs/
> Documentation index: https://ports.io/llms.txt

Connect your application to residential proxies. Learn how to authenticate, choose a location, keep a session, and understand your usage.

## Make your first request

Create a proxy key as a workspace owner or admin, obtain your assigned HTTP or SOCKS5 proxy URL, and send a request through `v1_rotate`.

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

Set `PORTS_PROXY_URL` to your assigned proxy URL, including its scheme, hostname, and port. Set `PORTS_PROXY_KEY` to the complete secret shown when you create a key.

For SOCKS5 with curl or Python Requests, use `socks5h://` so the destination hostname reaches the proxy for the exit to resolve. Their `socks5://` mode sends a locally resolved IP address, which is refused. Use a destination hostname and the assigned SOCKS port; an HTTPS proxy's TLS-only port cannot be reused just by changing the URL scheme. HTTP proxies use the assigned `http://` or `https://` URL. See [Protocols and limits](https://ports.io/docs/reference/protocols-and-limits.md) for transport details.

## Connect your application

- [Quickstart](https://ports.io/docs/guides/quickstart.md): Make your first request with an HTTP proxy or SOCKS5 with remote DNS.
- [curl](https://ports.io/docs/guides/curl.md): Configure HTTP or socks5h proxies and inspect failures with curl.
- [Python](https://ports.io/docs/guides/python.md): Use Requests with HTTP proxies or socks5h for remote DNS.
- [JavaScript](https://ports.io/docs/guides/javascript.md): Use Undici for HTTP proxies or SOCKS5 with destination DNS at the proxy.

## Routing reference

- [Authentication](https://ports.io/docs/reference/authentication.md): Authenticate HTTP or SOCKS5 with a routing username and your key as the password.
- [Username format](https://ports.io/docs/reference/username-reference.md): The complete grammar, its clauses, and the validation rules.
- [Geographic targeting](https://ports.io/docs/reference/targeting.md): Filter exits by country or by region.
- [Sessions and rotation](https://ports.io/docs/reference/sessions.md): Rotate exits, or keep related connections on one.

## Account and operations

- [Manage proxy keys](https://ports.io/docs/reference/key-lifecycle.md): Create, rename, replace, and revoke keys.
- [Usage measurement](https://ports.io/docs/guides/usage.md): What the console's traffic counters include.
- [Protocols and limits](https://ports.io/docs/reference/protocols-and-limits.md): HTTP and SOCKS5 support, remote DNS, size limits, and deadlines.
- [Troubleshooting](https://ports.io/docs/reference/troubleshooting.md): Diagnose HTTP proxy errors and SOCKS5 handshake or tunnel failures.

## Use these docs with AI tools

Every page is also published as Markdown at its address with `.md` in place of the final slash. Start an assistant from [llms.txt](https://ports.io/llms.txt), an index of every page, or give it [llms-full.txt](https://ports.io/llms-full.txt) for everything in one file. The [AI tools guide](https://ports.io/docs/guides/ai-tools.md) shows how to set up Claude Code, Codex and Cursor. Never include actual proxy secrets in prompts.