Authentication

A self-serve account gives you secrets shown once at registration:

Save your whisker key. We store only a peppered verifier and per-life paw keys — never the whisker itself and never a reusable plaintext password. There is no email or recovery on file (that's the point).

After signup you will see the whisker one more time on your first visit to the account dashboard, then never again.

Proxy authentication (collar + pawprint)

Authenticate each proxy session with your composed username (collar plus optional routing tags) and a pawprint:

• HTTP/HTTPS — Proxy-Authorization: Basic base64(username:pawprint), or the http://username:pawprint@host:port form your client builds.
• SOCKS5 — username/password method (RFC 1929).
• SOCKS4/4a — supported; the userid field carries the username.

At signup you receive a full pawprint (life 1, any scope). It works with any routing tags on the username. You can also derive scoped pawprints locked to one exit selection — a leaked scoped pawprint cannot be reused outside that scope.

# full pawprint from signup — any route
curl -x socks5h://cat-J5K2M4Q7X9A3F6H8-country-us:0a6b52bfad0cab7a8fa5b56e213ff032@socks.cat:1337 https://api.ipify.org

Deriving pawprints in the web UI

Open Account settings:

• Derive full pawprint — works with any routing tags.
• Derive for builder selection — scoped to your current dashboard route.
• Rotate — bumps life; old pawprints expire after the grace window (~24h).
• Reissue — new whisker key; kills every prior credential immediately.

Deriving pawprints offline

Everything is HMAC-SHA256 with versioned context strings. Stock openssl reproduces the vectors:

W='whisker-AAAA-BBBB-CCCC-DDDD-EEEE-FFFF-GGGG-HHHH-IIII-JJJJ-KKKK-LLLL-MMMM'
LIFE=1
K=$(printf 'socks.cat/v1/paw/%s' "$LIFE" | openssl dgst -sha256 -hmac "$W" -hex | awk '{print $NF}')

# full pawprint (any route)
printf 'socks.cat/v1/pw/*' | openssl dgst -sha256 -mac HMAC -macopt hexkey:$K -hex \
  | awk '{print substr($NF,1,32)}'

Replace LIFE after a rotation. For scoped pawprints, derive once in Account settings and copy the result — the scope string is computed from your builder selection (country/state/city + type + isp), not something you type into proxy clients.

Rotation and grace

Rotate bumps the life counter and invalidates old pawprints after a grace window (default 24 hours). Reissue mints a new whisker key and immediately kills every prior pawprint — use only if the whisker itself is compromised.

Account management

Sign in at /account with your whisker key, not your collar tag. The collar is public; presenting it to management endpoints does nothing.

IP authentication

Authorize a source IP or CIDR on your account page and connect with no username and no password:

# from an allowed IP — no credentials
curl -x socks5h://socks.cat:1337 https://api.ipify.org

IP-authed connections have no username, so they use your account's default selection. Set that in the endpoint builder.

Username/password and IP auth coexist: valid credentials win; otherwise the source IP is checked.

Balance

Traffic from every session — however you authed — is debited from your account's shared traffic quota. At zero, sessions are refused until you top up.