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

# Required.
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_customer","get_orders"]}]'

# Optional. Omit these to use defaults or disabled behavior.
# GATEWAY_ADDR=:8080
# GATEWAY_PUBLIC_URL=https://gateway.example.com
# GATEWAY_CORS_ALLOWED_ORIGINS=https://cors.example.com
# 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
# GATEWAY_EMIT_OPENAPI_SNAPSHOT=false

Variables

The full list of gateway environment variables, with defaults and descriptions, is the Environment Variables reference. The only required variables are GATEWAY_AGENT_PUBLIC_KEY and GATEWAY_API_KEYS_JSON; everything else is optional.

All optional variables may be omitted. Empty values are treated the same as omitted values. Invalid configured values are startup errors; the gateway does not silently fall back to defaults when a configured value is invalid.

The sections below explain the most operationally important variables in more detail.

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.

Public URL

Set GATEWAY_PUBLIC_URL to the external HTTP(S) base URL clients should call. Gateway writes this value into OpenAPI servers, including /openapi.json and the optional openapi_snapshot stdout event.

GATEWAY_PUBLIC_URL=https://gateway.example.com

When omitted, gateway derives a direct-access fallback from GATEWAY_ADDR, such as http://localhost:8080. For reverse proxy or load balancer deployments, set GATEWAY_PUBLIC_URL explicitly.

CORS

Set GATEWAY_CORS_ALLOWED_ORIGINS when browser-based clients, such as Swagger UI hosted on another origin, need to call the gateway directly.

GATEWAY_CORS_ALLOWED_ORIGINS=https://cors.example.com

The gateway allows GET, POST, and OPTIONS with Authorization, X-API-Key, and Content-Type only for configured origins. When omitted, the gateway does not emit CORS headers.

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_customer", "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