Private Endpoints

Private Endpoints

When you bind a port with --private, the endpoint requires authentication. Only members of your account can access it.

heyvm bind my-sandbox 8080 --private

How Authentication Works

Private endpoints are gated by JWT-based account membership. The proxy checks that the request includes a valid token whose account_id matches the endpoint owner's account.

Browser Access

When you visit a private endpoint URL in a browser without a valid session:

1. You are redirected to a login page
2. After authenticating (email/password or API key), a __heyo_token cookie is set on the .heyo.computer domain
3. Subsequent requests include this cookie automatically

API / CLI Access

For programmatic access, include a Bearer token in the Authorization header:

curl -H "Authorization: Bearer $HEYO_TOKEN" https://my-slug.heyo.computer/api/data

The token must be a valid JWT with an account_id claim matching the endpoint's account.

Getting a Token

You can obtain a token through:

• heyvm login — authenticates and stores credentials locally
• API key exchange — POST /api/api-keys/exchange with your API key returns a JWT
• Login API — POST /api/auth/login with email/password returns a JWT

Response Codes

Cross-Device Access

To access a private endpoint from another device:

1. Run heyvm login on the second device (same account)
2. Use heyvm list --format json to discover the endpoint URL
3. Access the URL — browser sessions auto-authenticate via the cookie; CLI/API clients use the Bearer token

Example: Private API with Client Access

# Deploy with a private port
heyvm deploy . --port 8080 --private --format json

# On another machine, after `heyvm login`:
TOKEN=$(cat ~/.heyo/credentials.json | jq -r '.token')
curl -H "Authorization: Bearer $TOKEN" https://my-slug.heyo.computer/api/data