> 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.

# Authenticate requests with Key Auth

> Require a gateway key on a route, choose the header that carries it, and troubleshoot authentication errors.

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](/fabric/gateways/llm-providers).
* 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.

> **Warning**
>
> 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**, 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**.

> **Warning**
>
> After you save, callers that still send the old header get a `401` response. You can't change the header back to a custom value.

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:

   ```json
   {
     "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](/fabric/plugins/routing).
* To review the request you sent, see [Inspect traces](/fabric/observability/traces).
* To add a rate limit to the route, see [Control traffic with plugins](/fabric/plugins).