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, how to send a test request, and how to troubleshoot authentication errors.

Prerequisites

Before you begin, make sure you have the following:

• A route with a gateway credential. The Create credential wizard in Credentials under Admin creates both. For the steps, see Connect an LLM provider.
• Postman, if you want to send the test request from a Postman collection.
• A gateway key for the route.

Understand gateway keys

When you finish the Create credential wizard, the last step creates a Key Auth plugin instance on the route. The instance closes the route to public access, so every caller needs a gateway key. For example, for a route called anthropic-route, Fabric names the instance route-auth--anthropic-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 selected JWT as the auth mode, an identity provider authenticates callers instead, and the Key Auth steps in this topic don’t apply.

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, and then open the Key Auth instance.

Move an older instance to fg-api-key

An instance created before the header became fixed can still use a custom header. For that instance, Request header shows both names, for example x-api-key or fg-api-key, and the gateway accepts a key in either header. This lets callers move to fg-api-key one at a time.

When every caller sends fg-api-key, do the following:

1. Open the plugin instance.
2. Next to Request header, select Accept fg-api-key only.
3. Select Save.

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 lists the keys configured for the route. Click Add key to add a key. Each key can map to a consumer.
• Edit as JSON switches the form to raw JSON. Match conditions and status expands the optional conditions.

Send a test request

Before you point an application at a route, confirm that the route works. Send a request through the gateway from Postman or with a cURL command. In a Postman collection, create a request with the following settings:

1. Set the method to POST and enter the following URL:

   https://<i>GATEWAY_HOST</i>/anthropic/v1/messages

   Replace GATEWAY_HOST with the data plane host for your organization. For a cloud tenant, the host has the form TENANT_NAME.dp.fabricgateway.ai. For an enterprise tenant, use the host of your own data plane.

2. In the Headers tab, add the following request headers:

   Key	Value
   fg-api-key	Your gateway key.
   anthropic-version	2023-06-01

3. In the Body tab, select raw and JSON, and then enter the following body:

   {
     "model": "claude-sonnet-4-5",
     "max_tokens": 256,
     "messages": [
       { "role": "user", "content": "Hello world!" }
     ]
   }

4. Click Send.

A successful request returns 200 OK. The response body contains an assistant message in the content array, with the name of the model that answered and token counts in the usage object. Your request doesn’t include the provider’s API key, because the gateway adds it.

Troubleshoot authentication errors

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

• The gateway rejects the request. Confirm that you send it in the fg-api-key header (or in the older header that Request header shows for a migrated instance), and that the key belongs to this route’s credential.

Next steps

• To choose which model or provider handles each request, see Route requests across models and providers.
• To review the request you sent, see Inspect traces.
• To add a rate limit to the route, see Control traffic with plugins.