Skip to main content

​
Authentication is optional

By default, Proxy Hopper accepts all requests with no authentication. This is fine for private, network-isolated deployments where trust is enforced at the network layer. Enable authentication when:
  • Proxy Hopper is reachable by multiple services or teams and you need to control who can use it
  • You want to restrict which services can access which targets
  • You are exposing Proxy Hopper outside a trusted network

​
Token types

Proxy Hopper supports three ways to authenticate: All three types use the same header for proxy requests:

​
How access control works

​
For API keys

API keys control access at the target level. Each key has a targets list:
  • targets: ["*"] — the key can send requests to any target
  • targets: ["maps", "geocoding"] — the key can only access the named targets
API keys are for proxy access only. They cannot call the admin API.

​
For local users and SSO

Users are assigned a role. Each role defines which targets it can access. Three roles are built in: Custom roles can be added in the auth.roles section to restrict access to specific targets.

​
Enabling authentication

Set jwtSecret to a long random string and keep it stable. If omitted, a secret is auto-generated at startup and all issued tokens become invalid on restart.Generate a secret:
Once auth.enabled: true is set:
  • All proxy requests must include X-Proxy-Hopper-Auth: Bearer <token>
  • Missing token → 401 Authentication required
  • Invalid/expired token → 401 Invalid or expired token
  • Valid token but target not permitted → 403

​
Admin API

The admin API (/health, /auth/login, /api/v1/status) runs on a separate port (adminPort, default 8081). It requires the admin API to be enabled and is not affected by proxy auth rules. See Config Reference for all auth fields.