Authentication
HPP Router authenticates consumers with an API key. Billing can use the prepaid quota rail (default) or the optional x402 wallet rail for on-chain settlement (commonly USDC.e).
Getting an API key
API keys can be issued from the HPP Router portal and also through HPP Hub. Treat the key like a password: keep it server-side and never commit it to source control.
Supported schemes
HPP Router accepts two authentication schemes. Use whichever fits your client.
1. apikey header (recommended)
- curl
curl https://router.hpp.io/llm/v1/chat/completions \
-H "apikey: $HPPROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"openai/gpt-5","messages":[{"role":"user","content":"Hello"}]}'
2. Bearer token
- curl
curl https://router.hpp.io/llm/v1/chat/completions \
-H "Authorization: Bearer $HPPROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"openai/gpt-5","messages":[{"role":"user","content":"Hello"}]}'
The Bearer scheme is what most OpenAI-compatible SDKs send by default, which is why the OpenAI SDK works as a drop-in: set the SDK's apiKey to your HPP Router key and it sends Authorization: Bearer ....
Which endpoints require auth
| Endpoint | Auth | Purpose |
|---|---|---|
GET /llm/v1/models | Optional | List models |
POST /llm/v1/chat/completions | Required for quota/keyed wallet; optional for Agent (keyless) | Chat completions |
POST /v1/images/generations | Required for quota/keyed wallet; optional for Agent (keyless) | Image generation |
GET /api/usage | Required | Usage summary |
GET /api/quota-check | Required | Check prepaid quota |
GET /api/user/audit/:logId | Required | Get user audit log |
GET /public/v1/agent-activity | None | Public x402 settlement feed (Agent guide) |
Quota and keyed wallet calls require an API key so Kong can identify the consumer. Keyed wallet payments additionally use X-Payment-Rail: wallet and an x402 signature.
Agent (keyless) omits the API key entirely: the gateway issues a 402 for paid models and settles after PAYMENT-SIGNATURE. See x402 Agent (keyless).
Payment rails
| Rail | Client signal | Notes |
|---|---|---|
| Quota (default) | API key, no X-Payment-Rail | Prepaid credit on the API key |
| Wallet (x402, keyed) | API key + X-Payment-Rail: wallet | On-chain settlement for paid models |
| Agent (x402, keyless) | No API key | Anonymous agent consumer; see x402 Agent |
x402 Wallet
When you send a request with X-Payment-Rail: wallet, the gateway uses the x402 protocol for payment authorization. If no payment signature is present for a paid model, the server responds with 402 and a PAYMENT-REQUIRED header (base64-encoded JSON). The JSON body includes an x402 accepts entry — typically scheme (upto), asset, amount (atomic/micro units), payTo, and network.
Retry once with the same request body plus PAYMENT-SIGNATURE (the gateway also accepts X-PAYMENT). Prefer @hpprouter/sdk with paymentRail + paymentSigner so this loop is automatic.
For agents that must call without an API key, use the Agent (keyless) path instead.
For protocol details, see:
Errors
A missing or invalid key returns 401. See Errors for the full list of status codes and the error envelope shape.
{ "error": "unauthorized", "message": "Invalid API key" }
Security tips
- Store the key in an environment variable or secret manager, never in client-side code.
- Rotate keys through the HPP Router portal or HPP Hub if a key may have been exposed.
- Prefer calling HPP Router from your backend so the key is never shipped to browsers or mobile apps.