Skip to navigation

Authenticate requests with Key Auth

A gateway route accepts requests only from callers that present a valid gateway key. The Key Auth plugin checks the key on each request. This topic explains how Key Auth is set up, which header carries the key, and how to troubleshoot authentication errors.

Prerequisites

Before you begin, make sure you have the following:

  • A route with Gateway auth set to Gateway key. Creating a connection with its default settings creates one. For the steps, see Connect an LLM provider.
  • A gateway key. Creating the connection doesn’t create one. To create it, select Credentials in the sidebar, and then select Create credential. For the steps, see Create a gateway key.

Understand gateway keys

When you create a connection with Gateway auth set to Gateway key, Fabric adds a Key Auth plugin instance to the new route. The instance closes the route to public access, so every caller needs a gateway key. Fabric names the instance route-auth-- followed by the route name. For example, for a route called anthropic-route, the instance is route-auth--anthropic-route.

The instance accepts every active gateway key in the namespace. A key isn’t tied to one route.

The gateway key is separate from the provider’s API key. The gateway key authenticates the caller to the gateway. The provider’s key authenticates the gateway to the provider, and Fabric adds it for you when it proxies the request.

If you authenticate callers with JWT Auth instead, an identity provider authenticates them, and the Key Auth steps in this topic don’t apply.

Treat gateway keys as secrets. Don’t share them in screenshots, recordings, or chat messages. If a key leaks, rotate it.

Choose the header that carries the key

Key Auth reads the gateway key from the fg-api-key request header. The console shows this under Request header, and you can’t edit it.

Providers read their own keys from provider-specific headers. For example, Anthropic reads its key from x-api-key. If the gateway key used the same header, a request couldn’t carry both keys, and clients couldn’t pass their own provider credentials through the gateway. A separate header avoids that conflict.

To check the header, select Plugins in the sidebar, select the Configured tab, and then open the Key Auth instance. You can also open it from the Plugins tab of the connection’s page.

On the same page, you can review or change the following settings:

  • Name and Plugin are read-only. You can’t change a plugin instance name after you create it.
  • Scope kind and Scope name show where the plugin runs. In this example, the scope is the route anthropic-route.
  • Keys is empty by default, which means the instance accepts every active gateway key in the namespace. If you select Add key and save, the instance accepts only the keys listed there, and new gateway keys stop working on the route. Each listed key must be the SHA-256 hash of the key, as 64 lowercase hexadecimal characters, not the key itself. Each key can map to a consumer.
  • Edit as JSON switches the form to raw JSON. Match conditions and status expands the optional conditions.

Test the route

To confirm that the route accepts the key, send a request through the gateway. For the steps, see Authenticate and send a request.

Troubleshoot authentication errors

If a request fails with an authentication error, check where the error comes from:

  • The gateway rejects the request with 401 Unauthorized. The key is missing, or it isn’t an active gateway key in this namespace. Confirm that you send the key in the fg-api-key header, and that the key is an active gateway key in the namespace that holds the route. If the instance lists its own Keys, the key must be one of them.

Next steps