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:
Token typeBest forConfig section
API keysService-to-service access (scripts, applications)auth.apiKeys
Local user accountsAdmin access with username + passwordauth.admin, auth.roles
SSO (OIDC)Enterprise identity providers (Azure AD, Authentik, Keycloak, Okta)auth.oidc
All three types use the same header for proxy requests: 
X-Proxy-Hopper-Auth: Bearer <token>

​
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:
RoleProxy accessTarget accessAdmin API
adminYesAll targetsYes — full access
operatorYesAll targetsNo
viewerNo—Read-only
Custom roles can be added in the auth.roles section to restrict access to specific targets.

​
Enabling authentication

auth:
  enabled: true
  jwtSecret: "change-me-to-a-long-random-string"
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:
openssl rand -base64 48
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.