> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Key Auth plugin

> Reference for the Key Auth plugin, which requires a gateway key in the fg-api-key header.

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

|             |                                                                                                                               |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Protocols   | HTTP, LLM, and MCP routes                                                                                                     |
| Scope kinds | `global`, `service`, `route`. The catalog also lists `consumer`, but a consumer-scoped instance never authenticates a caller. |
| Phase       | Authentication, 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`** `string` — required

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 strings` — default: 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

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

## Related guides

* [Authenticate requests with Key Auth](/configure/authentication/key-auth)
* [Authenticate and send a request](/use/authenticate)