API Keys

API keys authenticate REST, MCP, and OpenAPI requests. They also define which capabilities the caller can use.

Create a Key


./onprest-gateway create-key --name partner-a --capabilities "get_customer,get_orders"

For an internal key that can call every capability:


./onprest-gateway create-key --name internal --capabilities "*"

Authorization Model

API key authorization is explicit.

`capabilities`	Meaning
`["get_customer"]`	Can call only `get_customer`
`["get_customer", "get_orders"]`	Can call only the listed capabilities
`["*"]`	Can call all capabilities
`[]` or omitted	Can call no capabilities

This same authorization is applied to:

POST /api/v1/capabilities/{name}
POST /mcp tools/call
POST /mcp tools/list
GET /openapi.json

For tools/list and /openapi.json, gateway filters the visible tools or paths by API key.

Authentication Headers

Use either bearer auth or X-API-Key.


Authorization: Bearer {api_key}


X-API-Key: {api_key}

Bearer auth is recommended for general clients. X-API-Key is available for environments where bearer headers are inconvenient.

Log Identity

The gateway logs the key name, not the plaintext API key.


{
  "event": "request",
  "api_key_name": "partner-a",
  "capability": "get_customer",
  "http_status": 200
}

Choose stable names that identify the integration, team, or tenant using the key.

Gateway accepts at most 100 configured API keys. Successful authentication is cached for up to five minutes in a bounded 1,024-entry in-memory cache keyed by a SHA-256 digest; plaintext API keys are never stored in that cache or written to logs. Cache-miss bcrypt verification is limited to four concurrent requests across the gateway. When all four slots are occupied, another uncached authentication attempt receives HTTP 429 GATEWAY_RATE_LIMITED immediately instead of adding more bcrypt CPU work. The source-IP rate limit still applies before authentication. Rotation or configuration changes require a gateway restart, which also clears the cache.