API Keys

API keys authenticate every REST, MCP, OpenAPI, and file download request, and each key lists the capabilities it may call.

Create a key

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

The command prints the plaintext key once, together with a bcrypt key_hash. Give the plaintext key to the caller and add only the hash to GATEWAY_API_KEYS_JSON:

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

Restart the gateway to apply changes. A gateway accepts up to 100 keys.

What a key may call

The same list decides which capabilities appear in /openapi.json and MCP tools/list for that key, and which returned files it may download. Prefer explicit lists; use "*" only for internal keys.

Sending the key

Use either header:

Authorization: Bearer {api_key}
X-API-Key: {api_key}

Authorization: Bearer works with most clients. X-API-Key is there for clients that cannot set it.

Names in logs

Gateway logs record the key’s name, never the key itself, so choose names that identify the integration or team, such as partner-a or crm-sync.

Rotating a key

To rotate a key, add a new entry under a new name, give the new key to the caller, restart, and remove the old entry once the caller has switched.