Authenticating

When is authentication required?

Authentication is optional and disabled by default. Your administrator will tell you if it’s enabled. When it is, every proxy request must include a valid token in the X-Proxy-Hopper-Auth header. Ask your administrator for:

An API key, or
Credentials to log in and obtain a JWT, or
Instructions for your organisation’s SSO (OIDC) setup

Sending the auth header

All token types use the same header:

X-Proxy-Hopper-Auth: Bearer <your-token>

This header is stripped before the request reaches the upstream API — the API you’re calling never sees it.

API key authentication

The simplest option for automated services. Your administrator generates a key and gives it to you.

import requests

session = requests.Session()
session.headers.update({
    "X-Proxy-Hopper-Target": "https://api.example.com",
    "X-Proxy-Hopper-Auth": "Bearer ph_your_api_key_here",
})

resp = session.get("http://proxy-hopper:8080/v1/data")

import httpx

client = httpx.Client(
    base_url="http://proxy-hopper:8080",
    headers={
        "X-Proxy-Hopper-Target": "https://api.example.com",
        "X-Proxy-Hopper-Auth": "Bearer ph_your_api_key_here",
    },
)
resp = client.get("/v1/data")

import aiohttp

async with aiohttp.ClientSession(headers={
    "X-Proxy-Hopper-Target": "https://api.example.com",
    "X-Proxy-Hopper-Auth": "Bearer ph_your_api_key_here",
}) as session:
    async with session.get("http://proxy-hopper:8080/v1/data") as resp:
        data = await resp.json()

curl -H "X-Proxy-Hopper-Target: https://api.example.com" \
     -H "X-Proxy-Hopper-Auth: Bearer ph_your_api_key_here" \
     http://proxy-hopper:8080/v1/data

Store your API key in an environment variable or secret manager — never hard-code it:

import os
import requests

session = requests.Session()
session.headers.update({
    "X-Proxy-Hopper-Target": "https://api.example.com",
    "X-Proxy-Hopper-Auth": f"Bearer {os.environ['PROXY_HOPPER_API_KEY']}",
})

If you have a Proxy Hopper username and password, log in to the admin API to get a short-lived JWT:

import httpx
import os

# Log in to get a JWT
auth_resp = httpx.post(
    "http://proxy-hopper:8081/auth/login",   # admin port
    json={
        "username": os.environ["PROXY_HOPPER_USER"],
        "password": os.environ["PROXY_HOPPER_PASSWORD"],
    },
)
auth_resp.raise_for_status()
token = auth_resp.json()["token"]
expires_in = auth_resp.json()["expires_in"]   # seconds

# Use JWT for proxy requests
client = httpx.Client(
    base_url="http://proxy-hopper:8080",
    headers={
        "X-Proxy-Hopper-Target": "https://api.example.com",
        "X-Proxy-Hopper-Auth": f"Bearer {token}",
    },
)
resp = client.get("/v1/data")

import requests, os

# Log in
auth_resp = requests.post(
    "http://proxy-hopper:8081/auth/login",
    json={
        "username": os.environ["PROXY_HOPPER_USER"],
        "password": os.environ["PROXY_HOPPER_PASSWORD"],
    },
)
token = auth_resp.json()["token"]

# Use JWT
session = requests.Session()
session.headers.update({
    "X-Proxy-Hopper-Target": "https://api.example.com",
    "X-Proxy-Hopper-Auth": f"Bearer {token}",
})
resp = session.get("http://proxy-hopper:8080/v1/data")

JWTs expire (default 60 minutes). For long-running processes, you’ll need to refresh the token periodically. A simple approach:

import time
import httpx

class ProxyHopperClient:
    def __init__(self, proxy_url, admin_url, username, password, target):
        self._proxy_url = proxy_url
        self._admin_url = admin_url
        self._credentials = {"username": username, "password": password}
        self._target = target
        self._token = None
        self._token_expiry = 0

    def _refresh_if_needed(self):
        if time.time() >= self._token_expiry - 60:   # refresh 60s before expiry
            resp = httpx.post(f"{self._admin_url}/auth/login", json=self._credentials)
            resp.raise_for_status()
            data = resp.json()
            self._token = data["token"]
            self._token_expiry = time.time() + data["expires_in"]

    def get(self, path, **kwargs):
        self._refresh_if_needed()
        return httpx.get(
            f"{self._proxy_url}{path}",
            headers={
                "X-Proxy-Hopper-Target": self._target,
                "X-Proxy-Hopper-Auth": f"Bearer {self._token}",
            },
            **kwargs,
        )

OIDC / SSO authentication

If your organisation uses SSO (Azure AD, Authentik, Keycloak, etc.), you exchange your identity provider credentials for a token, then use that token with Proxy Hopper:

import httpx, os

# 1. Fetch a token from your IdP (client credentials flow)
idp_resp = httpx.post(
    os.environ["IDP_TOKEN_URL"],
    data={
        "grant_type": "client_credentials",
        "client_id": os.environ["IDP_CLIENT_ID"],
        "client_secret": os.environ["IDP_CLIENT_SECRET"],
        "scope": "openid",
    },
)
token = idp_resp.json()["access_token"]

# 2. Use the token with Proxy Hopper
client = httpx.Client(
    base_url="http://proxy-hopper:8080",
    headers={
        "X-Proxy-Hopper-Target": "https://api.example.com",
        "X-Proxy-Hopper-Auth": f"Bearer {token}",
    },
)
resp = client.get("/v1/data")

Error responses

Status	Meaning	Fix
`401 Authentication required`	`X-Proxy-Hopper-Auth` header is missing	Add the header
`401 Invalid or expired token`	Token not recognised or JWT has expired	Check the key value; re-login for a fresh JWT
`403`	Token is valid but target access not permitted	Ask your administrator to expand your API key’s `targets` list or assign a different role

Getting Started

Concepts

For Administrators

For Developers

For Contributors

When is authentication required?

Sending the auth header

API key authentication

OIDC / SSO authentication

Error responses

​When is authentication required?

​Sending the auth header

​API key authentication

​JWT authentication (login first)

​OIDC / SSO authentication

​Error responses

When is authentication required?

Sending the auth header

API key authentication

JWT authentication (login first)

OIDC / SSO authentication

Error responses