# Proxy authentication

> Authenticate HTTP or SOCKS5 with a routing username and your key as the password.
>
> Web page: https://ports.io/docs/reference/authentication/
> Documentation index: https://ports.io/llms.txt

Authenticate each new proxy connection with a routing username and the complete proxy key secret as the password. HTTP proxies carry these credentials in Basic authentication; SOCKS5 carries them in its username/password handshake. Both protocols use the same credentials and routing rules.

## Credentials at a glance

| Field | Value | Purpose |
| --- | --- | --- |
| Proxy endpoint | Your assigned proxy URL | Connects your client to the proxy service |
| Username | `v1_rotate`, or another valid routing username | Selects rotation, a session, and optional geographic filters |
| Password | Your complete `rp1_...` secret | Authorizes proxy connections for its workspace |

The example prefix `rp1_...` is a placeholder. Supply the complete secret, without extra whitespace or a newline. A key's display name, ID, or visible suffix cannot be used as its password.

## Make an authenticated request

Configure your assigned endpoint and a secret in your environment, then let the client construct the protocol's authentication exchange:

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

`PORTS_PROXY_URL` and `PORTS_PROXY_KEY` are application variables used in this example. Their values must come from your service configuration and key creation flow. Include the assigned scheme, hostname, and port; do not infer a SOCKS port from an HTTPS proxy URL.

For curl, use an assigned `http://` or `https://` proxy URL for HTTP proxying, or `socks5h://` for SOCKS5 with remote DNS. An HTTPS destination establishes the corresponding tunnel and then negotiates TLS with the destination. See [Protocols and limits](https://ports.io/docs/reference/protocols-and-limits.md) for transport details.

## HTTP wire format

Clients send one `Proxy-Authorization` header on the initial proxy request:

```http
CONNECT example.com:443 HTTP/1.1
Host: example.com:443
Proxy-Authorization: Basic <base64-of-username:password>
```

The Base64 input is the UTF-8 string `username:password`. Use the standard Basic authentication encoder in your HTTP library. Do not send the key in an origin `Authorization` header, a URL query parameter, or a custom bearer header.

Basic authentication encoding does not encrypt the credentials. Use the proxy transport supplied for your environment and protect the key as a secret.

## SOCKS5 authentication and remote DNS

Configure SOCKS5 username/password authentication ([RFC 1929](https://www.rfc-editor.org/rfc/rfc1929)) with the routing username and full key. Do not Base64-encode the password or send an HTTP `Proxy-Authorization` header inside the SOCKS handshake. The gateway does not accept anonymous authentication.

With curl or Python Requests, set `PORTS_PROXY_URL` to the assigned SOCKS endpoint using `socks5h://`. This sends the destination hostname to the proxy for the exit to resolve. Their `socks5://` mode sends a locally resolved IP address, which is refused because destinations must be hostnames. The `h` selects remote DNS; it does not encrypt the proxy connection.

The username and password are each limited to 255 UTF-8 bytes. Send the complete key. See the [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) guide for client-specific configuration.

## Change routing without replacing the key

The same key can authenticate different routing usernames:

```text
v1_rotate
v1_rotate_countries_US
v1_sticky_session_checkout-42_countries_US
v1_fixed_session_audit-42_regions_EU
```

The username never needs an account or workspace ID. The verified password identifies the workspace automatically. See [Username reference](https://ports.io/docs/reference/username-reference.md) for the complete grammar.

## Authentication failures

HTTP authentication failures return `407` with `Proxy-Authenticate: Basic`. The error code distinguishes `invalid_credentials`, `key_expired`, `key_revoked`, and `account_disabled`.

SOCKS5 authentication failures return an RFC 1929 failure status, without HTTP headers or a JSON error body. Invalid usernames, invalid keys, expired or revoked keys, and disabled workspaces use the same failure status. A client that does not offer username/password authentication receives a no-acceptable-methods reply before authentication starts.

Check the whole username and password together: an unsupported username is also an authentication failure. Modified or wrong-environment secrets are rejected. If an unchanged key suddenly fails across otherwise valid requests, use the [troubleshooting guide](https://ports.io/docs/reference/troubleshooting.md) before creating replacement keys. Revocation and workspace status changes have a [propagation interval](https://ports.io/docs/reference/key-lifecycle.md#revoke-or-expire-a-key).

## Protect credentials

- Store secrets in a secret manager or environment configuration.
- Keep them out of source code, browser-delivered applications, request logs, screenshots, and support messages.
- Use separate keys for applications that need independent revocation.
- Replace a leaked or lost key using the [key lifecycle guide](https://ports.io/docs/reference/key-lifecycle.md).

A proxy key grants proxy connection access. It is not a management API token.