> 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 JWT Auth

> Authenticate callers with JSON Web Tokens from your identity provider, and use token claims to control which tools an agent can use.

Key Auth and JWT Auth are the two main ways to authenticate callers on a route. Key Auth checks a gateway key. JWT Auth checks a JSON Web Token (JWT) that your identity provider (IdP), such as Okta, issued. The gateway validates the token, reads its claims, and passes them on, so that other plugins can enforce policy on them. This topic explains how JWT Auth works and how to combine it with the Agent Scope Gate plugin to limit which MCP tools a user can see.

> **Info**
>
> JWT Auth isn't available when Postman hosts your data plane. It validates tokens against an identity provider that you register with the gateway, and the console shows a warning on the plugin form when you use a Postman-hosted data plane. For more information, see [Choose a deployment model](/evaluate/deployment-models).

## Understand JWT Auth

The plugin validates each token against the signing keys that your identity provider publishes. If the token is valid, the gateway treats the request as authenticated and maps claims from the token to the caller's identity. Other plugins on the route can then use those claims.

Choose JWT Auth over Key Auth when your users or agents already sign in through an identity provider and you want the gateway to use that identity instead of a separate gateway key.

## Configure JWT Auth

To add JWT Auth to a route, do the following:

1. Select **Plugins**, find **JWT Auth** in the **Auth** category, and then select **Use**.

2. Enter a **Name**, set **Scope kind** to `route`, and set **Scope name** to the route that you want to protect.

3. In **Identity provider**, select the identity provider that you registered with the gateway. This field is required. An instance without an identity provider doesn't authenticate requests.

4. Optionally, open **Advanced settings** and adjust the following settings:

   | Setting                                                                                                                                                                            | What it does                                                                                                                                   |
   | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
   | **Token sources**                                                                                                                                                                  | Where the gateway reads the token, in order. The first match wins. Leave it empty to read a bearer token from the `Authorization` header.      |
   | **Subject claim**, **Principal claim**, **Kind claim**, **Scopes claim**, **Tenant claim**, **User claim**, **Session claim**, **Installation claim**, and **Consumer type claim** | The names of the claims that the gateway reads. Each has a default, for example `sub` for **Subject claim** and `scopes` for **Scopes claim**. |

5. Select **Save**.

> **Warning**
>
> If you read the token from a cookie, browsers send it automatically, so the request is exposed to cross-site request forgery. Set the cookie `HttpOnly` and `Secure` with `SameSite=Lax` or `Strict`, and require a CSRF token on requests that change state. The gateway validates the token but doesn't add CSRF protection.

## Limit MCP tools with claims

The Agent Scope Gate plugin checks the scopes on the authenticated caller before it lets a request through. When the caller's scopes come from JWT claims, you can control what each person or agent can do.

By default, Agent Scope Gate checks only agent traffic. To also check requests from people, such as users who sign in through your identity provider, select **Apply to humans**.

To configure the Agent Scope Gate, do the following:

1. Select **Plugins**, find **Agent Scope Gate**, and then select **Use**.
2. Enter a **Name**, and set the scope to the MCP route.
3. In **Required scopes**, enter the scopes that the caller must have, as a comma-separated list, for example `workspace:read, agent:run`.
4. In **Scope match**, choose whether the caller needs all of the scopes or any of them.
5. To check people as well as agents, select **Apply to humans**.
6. Select **Save**.

You can also require a consumer group with **Require consumer group**, and allow only certain principal types, such as `bot` or `human`, with **Allow principal types**. A request without the required scopes is rejected.

### Set scopes for individual tools

To require different scopes for individual MCP tools, for example a scope that allows delete tools, add a `tool_scopes` map to the configuration. The form doesn't show this setting, so select **Edit as JSON** and add it there. For example:

```json
{
  "tool_scopes": {
    "delete_dashboard": ["agent:dangerous"]
  }
}
```

**Tool scope match** controls whether a caller needs all of a tool's scopes or any of them. A call to a tool without its scopes is rejected. For agents, the gateway also hides those tools from the tool list. People still see every tool in the list, but with **Apply to humans** selected, their calls to a tool without its scopes are rejected.

## Next steps

* For the plugin's configuration schema, see the [JWT Auth plugin](/reference/plugins/jwt-auth).
* To require a gateway key instead, see [Authenticate requests with Key Auth](/configure/authentication/key-auth).
* To connect an MCP server that this plugin protects, see [Connect an MCP server](/configure/connections/mcp-servers).