Skip to Content
GatewayConfiguration

Gateway Configuration

onprest-gateway is configured with environment variables. Configuration is process-scoped, so each customer should have a dedicated gateway, dedicated env, dedicated agent public key, and dedicated API keys.

Example

GATEWAY_ADDR=:8080
GATEWAY_AGENT_PUBLIC_KEY=base64url-ed25519-public-key
GATEWAY_API_KEYS_JSON='[{"name":"internal","key_hash":"$2a$10$xxxxx","capabilities":["*"]},{"name":"partner-a","key_hash":"$2a$10$xxxxx","capabilities":["get_customers","get_orders"]}]'
GATEWAY_IP_ALLOW_LIST=203.0.113.0/24,198.51.100.0/24
GATEWAY_TRUSTED_PROXY_CIDRS=172.16.0.0/12
GATEWAY_RATE_LIMIT_REQUESTS_PER_SECOND=10
GATEWAY_RATE_LIMIT_BURST=20

Variables

VariableRequiredDescription
GATEWAY_ADDRNoListen address, default :8080
GATEWAY_AGENT_PUBLIC_KEYYesEd25519 public key used to verify agent WebSocket signatures
GATEWAY_API_KEYS_JSONYesJSON array of API key names, bcrypt hashes, and allowed capabilities
GATEWAY_IP_ALLOW_LISTNoComma-separated CIDRs or single IPs allowed to call protected endpoints
GATEWAY_TRUSTED_PROXY_CIDRSNoCIDRs whose forwarded headers are trusted for source IP detection
GATEWAY_RATE_LIMIT_REQUESTS_PER_SECONDNoPer-source request rate, default 10
GATEWAY_RATE_LIMIT_BURSTNoPer-source burst size, default 20

Invalid rate limit values are startup errors. gateway does not silently fall back to defaults when a configured rate or burst value is invalid.

Listen Address

Use GATEWAY_ADDR to bind gateway to a specific address or port.

GATEWAY_ADDR=127.0.0.1:8080

When omitted, gateway listens on :8080.

Agent Public Key

Generate the agent key pair with the gateway CLI.

./onprest-gateway create-agent-secret

The public key goes into GATEWAY_AGENT_PUBLIC_KEY. The private key goes into capability.yaml on the agent side.

API Keys JSON

GATEWAY_API_KEYS_JSON is a JSON array.

[
  {
    "name": "partner-a",
    "key_hash": "$2a$10$xxxxx",
    "capabilities": ["get_customers", "get_orders"]
  }
]

The name is used in access logs. The plaintext key is shown only when generated by create-key; gateway stores and verifies the bcrypt hash.

Shell Quoting

bcrypt hashes contain $. When loading env files with a shell, wrap the whole JSON value in single quotes.

GATEWAY_API_KEYS_JSON='[{"name":"dev","key_hash":"$2a$10$...","capabilities":["*"]}]'

Without single quotes, shells may expand $2a, $10, or later segments and corrupt the hash.

OverviewAPI Keys