Skip to navigation

Key Auth plugin

The Key Auth plugin identifies the caller from a gateway key in the fg-api-key request header. A matching key identifies the consumer that owns it. A missing or unknown key gets a 401 Unauthorized response, and the two cases look the same to the client. The gateway removes the key header before it forwards the request, so the key never reaches the upstream.

Where it runs

ProtocolsHTTP, LLM, and MCP routes
Scope kindsglobal, service, route. The catalog also lists consumer, but a consumer-scoped instance never authenticates a caller.
PhaseAuthentication, before other request plugins

Configuration

You usually don’t set the keys yourself. When an instance doesn’t list keys, the control plane fills it with the keys of the Key Auth credentials in the instance’s namespace, stored as SHA-256 hashes. Inactive credentials are left out. An instance whose namespace has no keys stays empty, and doesn’t borrow keys from other namespaces.

header
stringRequired

The header that carries the gateway key. Must be fg-api-key. Instances stored with another header before this rule keep it, and also accept fg-api-key.

keys
array of stringsDefaults to Filled from consumers' credentials

SHA-256 hashes of the accepted keys, each 64 lowercase hexadecimal characters, not the keys themselves. Adding even one key pins the instance: the control plane stops filling in keys from credentials, and the instance accepts only the keys you list.

headers
array of strings

Headers to read the gateway key from, instead of header. Any header names are allowed. Authorization counts only as Bearer <key>. When you set this list, the instance reads only the listed headers, so add fg-api-key to it if callers still send that. If two listed headers carry different keys, the request gets 401 with conflicting credentials.

consumers
object

Maps a key hash to the consumer that it identifies. Your entries are added to the keys from credentials, and win when both name the same key.

credential_ids
object

Maps a key hash to a credential ID. Used only to label traces and metrics.

An instance at route or connection scope that has no keys at all refuses every request with 401.

Example

{
"name": "route-auth--anthropic-route",
"plugin_id": "key-auth",
"scope": { "kind": "route", "name": "anthropic-route" },
"config": { "header": "fg-api-key" }
}